From Gentoo Wiki
(Redirected from Emerge)
Jump to:navigation Jump to:search

Portage is the official package manager and distribution system for Gentoo. It functions as the heart of Gentoo-based operating systems. Portage provides advanced dependency resolution, flexible building and installation of software from source, and includes facilities to produce, manage, and distribute binary files - among other things.

Portage will provision software from the Gentoo ebuild repository, as well as from any additional repositories, as necessary . Portage includes many commands for repository and package management, the primary of which is the emerge command.

The most common questions about portage and the emerge command are handled in the Portage FAQ.

This article describes Portage from a user's perspective. Those looking to contribute to Portage development should visit the Portage project page


All Gentoo installations come with Portage, so there is no need to install it! The rest of this section deals with the very rare occurrence of a "broken" portage installation, feel free to skip to the next section.

Although it should be very rare, as with all data, there remains a possibility that Portage could become corrupt or even uninstalled, which would be very bad for the functioning of the whole system. If ever this were to occur, there are ways Portage can be recovered, however, because Portage is so central, re-installation is a rather involved operation, requiring manual intervention to, in effect, install a package manager without having a functioning package manager.

See Fix my Gentoo for details on emergency installation via binary packages. See also Fixing broken Portage.


In order for Gentoo to stay up to date, Portage must stay up to date. Generally the usual, regular updating of Gentoo, will automatically update Portage without issue.

On occasion, updates to Portage can make it necessary to update Portage before the rest of the system. After synchronizing Portage, a message requesting this may be displayed, and it is important to follow it:

* An update to portage is available. It is _highly_ recommended
* that you update portage now, before any other packages are updated.

* To update portage, run 'emerge --oneshot sys-apps/portage' now.

Emerge Portage as advised (adapt the command if the message differs from this example). The --oneshot option is important, to avoid adding sys-apps/portage to the world file:

root #emerge --ask --oneshot sys-apps/portage

If there is an issue with updating Portage, User:Sam/Portage_help/Upgrading_Portage may help.



/etc/portage directory

There are many files used to configure Portage, though the main Portage configuration is in make.conf.

See /etc/portage configuration files for an exhaustive list of configuration files.


The /usr/share/portage/config/make.globals file contains many default configuration values sourced by Portage. These values can be overwritten by specifying the same variable names in /etc/portage/make.conf.

Environment variables

Portage can be configured to a vast extent through environment variables.

See man emerge for some information on available environment variables and the Handbook section for working with environment variables in Gentoo.

To view all presently set environment variables, run:

user $emerge --info --verbose

Environment variables can be set on a per-package basis via /etc/portage/package.env entries.

Ebuild repositories

In addition to the Gentoo ebuild repository, from which Portage will pull packages by default, additional ebuild repositories are available:

  • repos.gentoo.org - list of repositories contributed by the community, some by Gentoo developers
  • GURU - official ebuild repository maintained collaboratively by Gentoo users, with a little support from a few Gentoo developers
  • gpo.zugaina.org - third-party list of ebuild repositories

The ebuild repository article has a section on configuring ebuild repositories to be used by Portage.

Search for available ebuilds on the command line with emerge --search or eix.

While the Gentoo ebuild repository is either written or reviewed by Gentoo developers, that is not always the case for other ebuild repositories. It is possible that some ebuilds repositories might contain vulnerable, badly broken or, theoretically, even malicious software.

Default Gentoo ebuild repository location change

As of portage v2.3.66[1], which was released on 2019-04-29[2], the default locations changed for the portdir, distdir, repo_name, repo_basedir directories.

For more information see bug bug #662982.

Old location

CODE Location before 2019-04-29

New location

CODE Location as of 2019-04-29 and later


Portage includes many different tools and utilities to help with system administration and maintenance. The following sections list these in alphabetical order.


The purpose of archive-conf is to save off a config file in the dispatch-conf archive directory. Most users should not ever need to run this command:

root #archive-conf
Usage: archive-conf /CONFIG/FILE [/CONFIG/FILE...]


The dispatch-conf utility is used to manage configuration file updates. See the dispatch-conf article.


ebuild is Portage's command for running the various ebuild functions. For disambiguation see the ebuild article.


The egencache tool rebuilds the cache of metadata information for the ebuild repositories. See the egencache article for additional information.


Performs package management related system health checks and maintenance.

See repository synchronization about how to use emaint to synchronize repositories. See man 1 emaint for detailed information.

The emerge --sync command is now implemented with emaint.


emerge is the command-line interface to Portage and is how most users will interact with Portage. The emerge command has many possible options. For a complete list of all options see its man page:

user $man emerge

Below is an example invocation of emerge. The options (-atv) are short options for --ask, --tree, and --verbose. They trigger emerge to ask before proceeding, display the dependency tree of packages to be installed, and to be verbose with its output.

# emerge -atv package

These are the packages that would be merged, in reverse order:

Calculating dependencies... done! [ebuild U ] category/package-3.0-r2 [2.0] USE="enabled -disabled toggled* new% (-unavailable)" MAKE_OPTIONS="-disabled" 777 kB [ebuild UD ] category/package-2.0 [3.0] 777 kB [ebuild R ] category/package-1.0 777 kB [ebuild N ] category/package-0.5 777 kB

Total: 4 packages (1 new, 1 reinstall, 1 upgrade, 1 downgrade), Size of downloads: 3108 kB

Would you like to merge these packages? [Yes/No]

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

Search for packages

Search for packages with proxy in their names:

user $emerge --search proxy

Search for packages with proxy in their names or description:

user $emerge --searchdesc proxy

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

Show more detailed information and ask for confirmation

The --ask option is very useful, it will allow the emerge actions to be reviewed before the actual operation begins.

The --verbose option will show more detailed information about what Portage will do, and is often helpful.

Install the net-proxy/tinyproxy package with --ask and --verbose options for precaution:

root #emerge --ask --verbose net-proxy/tinyproxy

Options can be set as default, if desired. Default options can be overridden on the command line, for example --ask=n.

Remove (uninstall) packages

Remove the net-proxy/tinyproxy package using the dependency sensitive --depclean option:

root #emerge --ask --verbose --depclean net-proxy/tinyproxy

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

Do not use the --unmerge option, unless its particular behavior is known to be specifically required. This option can remove important packages that are needed for the system to function.
Cleaning out orphaned packages

When packages have been removed, their dependencies are left installed, in case other packages might use them. These packages can be removed, to recover storage space:

user $emerge --pretend --depclean

If emerge --depclean has not been run in a while, it may try to remove many packages - caution is advised.

Running emerge --depclean can in some cases try to remove important packages. Check the provided list of "obsoleted" packages to make sure it doesn't remove packages that are needed. Take particular care not to remove current kernel sources, a required version of GCC, or required packages that were tacitly installed as a virtual package dependency, for example.

See remove orphaned packages for information on how to use emerge --depclean, and also the Portage FAQ.

Verifying and (re)downloading distfiles

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

root #emerge --ask --fetchonly --emptytree @world


root #emerge-webrsync -h
Usage: /usr/bin/emerge-webrsync [options]
  --revert=yyyymmdd   Revert to snapshot
  -k, --keep          Keep snapshots in DISTDIR (don't delete)
  -q, --quiet         Only output errors
  -v, --verbose       Enable verbose output
  -x, --debug         Enable debug output
  -h, --help          This help screen (duh!)

emerge-webrsync is called internally by eix-sync when sync-type in /etc/portage/repos.conf is set to webrsync.


root #emirrordist -h
usage: emirrordist [options] <action>
emirrordist - a fetch tool for mirroring of package distfiles
optional arguments:
  -h, --help            show this help message and exit
  --version             display portage version and exit
  --mirror              mirror distfiles for the selected repository
Common options:
  --dry-run             perform a trial run with no changes made (usually
                        combined with --verbose)
  --verbose, -v         display extra information on stderr (multiple
                        occurences increase verbosity)
                        do not use the EMIRRORDIST_DEFAULT_OPTS environment
  --distfiles DIR       distfiles directory to use (required)
  --jobs JOBS, -j JOBS  number of concurrent jobs to run
  --load-average LOAD, -l LOAD
                        load average limit for spawning of new concurrent jobs
  --tries TRIES         maximum number of tries per file, 0 means unlimited
                        (default is 10)
  --repo REPO           name of repo to operate on
  --config-root DIR     location of portage config files
  --repositories-configuration REPOSITORIES_CONFIGURATION
                        override configuration of repositories (in format of
  --strict-manifests <y|n>
                        manually override "strict" FEATURES setting
  --failure-log FILE    log file for fetch failures, with tab-delimited
                        output, for reporting purposes
  --success-log FILE    log file for fetch successes, with tab-delimited
                        output, for reporting purposes
  --scheduled-deletion-log FILE
                        log file for scheduled deletions, with tab-delimited
                        output, for reporting purposes
  --delete              enable deletion of unused distfiles
  --deletion-db FILE    database file used to track lifetime of files
                        scheduled for delayed deletion
  --deletion-delay SECONDS
                        delay time for deletion, measured in seconds
  --temp-dir DIR        temporary directory for downloads
  --mirror-overrides FILE
                        file holding a list of mirror overrides
  --mirror-skip MIRROR_SKIP
                        comma delimited list of mirror targets to skip when
  --restrict-mirror-exemptions RESTRICT_MIRROR_EXEMPTIONS
                        comma delimited list of mirror targets for which to
                        ignore RESTRICT="mirror"
                        use digest as a verification of whether existing
                        distfiles are valid
  --distfiles-local DIR
                        distfiles-local directory to use
  --distfiles-db FILE   database file used to track which ebuilds a distfile
                        belongs to
  --recycle-dir DIR     directory for extended retention of files that are
                        removed from distdir with the --delete option
  --recycle-db FILE     database file used to track lifetime of files in
                        recycle dir
  --recycle-deletion-delay SECONDS
                        delay time for deletion of unused files from recycle
                        dir, measured in seconds (defaults to the equivalent
                        of 60 days)
  --fetch-log-dir DIR   directory for individual fetch logs
  --whitelist-from FILE
                        specifies a file containing a list of files to
                        whitelist, one per line, # prefixed lines ignored


root #env-update -h
Usage: env-update [--no-ldconfig]

See the env-update(1) man page for more info


dispatch-conf is now the recommended way to manage configuration file changes. Importantly, dispatch-conf permits the rollback of config changes.
root #etc-update -h
etc-update: Handle configuration file updates
Usage: etc-update [options] [paths to scan]
If no paths are specified, then ${CONFIG_PROTECT} will be used.
  -d, --debug    Enable shell debugging
  -h, --help     Show help and run away
  -p, --preen    Automerge trivial changes only and quit
  -q, --quiet    Show only essential output
  -v, --verbose  Show settings and such along the way
  -V, --version  Show version and trundle away
  --automode <mode>
             -3 to auto merge all files
             -5 to auto-merge AND not use 'mv -i'
             -7 to discard all updates
             -9 to discard all updates AND not use 'rm -i'


root #fixpackages -h
usage: fixpackages [-h]

The fixpackages program performs package move updates on configuration files,
installed packages, and binary packages.

optional arguments:
  -h, --help  show this help message and exit


root #regenworld -h
This script regenerates the portage world file by checking the portage
logfile for all actions that you've done in the past. It ignores any
arguments except --help. It is recommended that you make a backup of
your existing world file (/var/lib/portage/world) before using this tool.


For details see portageq.


See the Binary package guide for more information.


repoman is a development tool used for testing ebuilds. Since version 2.3.0, it is packaged separately from Portage, in app-portage/repoman. See the repoman article for additional information.


Gentoo Linux Security Announcements (GLSAs) are notifications sent out to the community to inform of security vulnerabilities related to Gentoo Linux or to packages contained in the repository.

glsa-check is a tool to keep track of the various GLSAs. It can be used to view GLSAs, but more importantly to test if the system is vulnerable to known GLSAs.

See "man glsa-check" and "glsa-check --help" for more information:

user $glsa-check --help
usage: glsa-check <option> [glsa-id | all | new | affected]
optional arguments:
  -h, --help        show this help message and exit
  -V, --version     Show information about glsa-check
  -q, --quiet       Be less verbose and do not send empty mail
  -v, --verbose     Print more messages
  -n, --nocolor     Removes color from output
  -e, --emergelike  Upgrade to latest version (not least-change)
  -c, --cve         Show CVE IDs in listing mode
  -r, --reverse     List GLSAs in reverse order
  -l, --list        List a summary for the given GLSA(s) or set and whether they affect the system
  -d, --dump        Show all information about the GLSA(s) or set
  --print           Alias for --dump
  -t, --test        Test if this system is affected by the GLSA(s) or set and output the GLSA ID(s)
  -p, --pretend     Show the necessary steps to remediate the system
  -f, --fix         (experimental) Attempt to remediate the system based on the instructions given in the GLSA(s) or set. This will only upgrade (when an upgrade path exists) or remove packages
  -i, --inject      Inject the given GLSA(s) into the glsa_injected file
  -m, --mail        Send a mail with the given GLSAs to the administrator
glsa-list can contain an arbitrary number of GLSA ids, filenames containing GLSAs or the special identifiers 'all' and 'affected'


Main (Gentoo) ebuild repository sync time

To see when the Gentoo ebuild repository was last updated (synced), run the following command:

user $cat /var/db/repos/gentoo/metadata/timestamp.chk

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:

user $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.

See also

Related to Portage

  • Upgrading Gentoo — explains how to upgrade (update) Gentoo.
  • Creating an ebuild repository — basics of creating an ebuild repository and maintaining ebuilds in it.
  • GCC optimization — an introduction to optimizing compiled code using safe, sane CFLAGS and CXXFLAGS.
  • Portage tips — contains a list of tips for Portage users
  • Repository format — A quick reference to Gentoo ebuild repository (overlay) format.
  • Package Manager Specification — a standardization effort to ensure that the ebuild file format, the ebuild repository format (of which the Gentoo ebuild repository is the main incarnation), as well as behavior of the package managers interacting with these ebuilds is properly agreed upon and documented.
  • Ebuild repository — a file-structure that can provide packages for installation on a Gentoo system.
  • Category:Portage
  • Gentoolkit — a suite of tools to ease the administration of a Gentoo system, and Portage in particular.
  • Portage Multi Stage Dockerfile — The emerge --quickpkg-direct and related emerge --quickpkg-direct-root options are useful inside Dockerfiles
  • Portage Security — aims to answer the question "How can I dispel doubts regarding the security of the Gentoo ebuild repository on a system?"
  • Portage TMPDIR on tmpfs — Building packages in tmpfs both speeds up emerge times and reduces HDD/SSD wear.

Portage in the Gentoo AMD64 Handbook

Portage tools

Alternate package managers and GUIs

  • Pkgcore — an alternative package manager for Gentoo that aims for high performance, extensibility, and a clean design.
  • Paludis — a multi-format package manager and an alternative to Portage.
  • app-portage/kuroo - Graphical Portage frontend based on KF5/Qt5.

External resources

  • packages.gentoo.org - online searchable database of packages from the Gentoo package repository.

Portage man pages

The man pages contain complete technical documentation for Portage. Type man <subject> in a shell on a Gentoo system to read the local man page. Note that man pages have a see also section for further information.