Portage

Portage is 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 command.

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

Installation
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.

Updating
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  option is important, to avoid adding  to the world file:

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

Files
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.

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

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

To view all presently set environment variables, run:

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 to extend the available software on systems:


 * repos.gentoo.org developer and community-contributed ebuild repositories
 * GURU - official ebuild repository maintained collaboratively by Gentoo users, with a little help 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 and eix.

Default Gentoo ebuild repository location change
As of portage v2.3.66, which was released on 2019-04-29 , the default locations changed for the portdir , distdir , repo_name , repo_basedir directories.

For more information see bug.

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

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

dispatch-conf
The 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.

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

emaint
Performs package management related system health checks and maintenance.

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

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

Below is an example invocation of. 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.

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:

Search for packages with proxy in their names or description:

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

Show more detailed information and ask for confirmation
The  option is very useful, it will allow the emerge actions to be reviewed before the actual operation begins.

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

Install the package with   and   options for precaution:

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

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.

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:

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

See remove orphaned packages for information on how to use, 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:

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

portageq
For details see portageq.

quickpkg
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. See the article for additional information.

glsa-check
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.

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:

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

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

Related to Portage

 * Category:Portage
 * Category:Portage
 * Category:Portage
 * Category:Portage
 * Category:Portage
 * Category:Portage
 * Category:Portage
 * Category:Portage

Portage in the Gentoo AMD64 Handbook

 * A Portage introduction
 * USE flags
 * Portage features
 * Files and directories
 * Configuring through variables
 * Mixing software branches
 * Additional Portage tools
 * Custom Portage tree
 * Advanced Portage features

Alternate package managers and GUIs

 * - Graphical Portage frontend based on KF5/Qt5.
 * - Graphical Portage frontend based on KF5/Qt5.
 * - 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 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.


 * emerge - command-line interface to the Portage system - emerge man page.
 * Portage configuration files - Portage man page.