Portage

Portage is package manager and distribution system for Gentoo.]] It functions as the heart of Gentoo-based operating systems. 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. Like all data, there is a possibility Portage can become corrupted or even uninstalled, which is very bad. If this is the case there are ways Portage can be recovered, however Portage re-installation can be quite a hassle. It becomes a work of manual labor: installing a package manager without a package manager.

Binary package
Have a friend or a build server build a Portage binary package, then boot a recovery disk and transfer the binary package to the broken machine. This could be done using the  Portage feature on a healthy machine or by using the  command (see the binary package guide). Portage will be needed in to order to install the binary package, however it is possible to run something off a virtual machine.

Boot up a LiveDVD/CD that has Portage included (Gentoo LiveDVDs should contain Portage). Remove the old or broken Portage and reinstall Portage to the mounted root filesystem (potentially the fastest and easiest option in the case of a fast internet connection and available CDs/DVDs). For example, if the root file system with broken Portage was mounted at the following commands could be used from a live environment.
 * 1) Change all of Portage's relevant environment variables to be set to the Portage directory of the mounted root filesystem. If the broken Portage root directory is mounted at, the command would look like this:
 * 2) Run the command in order to remove any traces of the old broken Portage package:
 * 3) Sync the system in case it is a bit behind on the current Gentoo repository:
 * 4) Install the new version of Portage:

Tarball
Manually download a copy of a recent Portage release tarball, extract it, and manually install it:

Install via :

If they do not exist, add the following lines into the following files:

Create the directory if it does not exist:

Updating
In order for Gentoo to stay up to date, Portage must stay up to date. If the following message is visible after an, it is important to do what the text says before updating other packages.

This is short hand expression for:

This will tell Portage to exclusively update itself. After Portage has been updated, users can then update other packages.

Files
There are many files used to configure Portage.

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

Environment variables
Portage pays attention to some environment variables:

Ebuild repositories
In addition to the Gentoo repository, there are additional ebuild repositories.


 * Gentoo hosted repositories
 * Browse ebuild repositories [3rd party]
 * Adding ebuild repositories to the installation

It is possible to search through the ebuilds available in the ebuild repositories on https://repos.gentoo.org/ by using the eix tool.

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
Implements the command. See Portage's sync operation and.

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 exemplary 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. While in the context of Portage, the term "package" can also be referred to as an "atom." Do not be confused if you see the term "atom" used instead of the term "package."

Common invocations
Search for packages with proxy in their names:

Search for packages with proxy in their names or description:

Install the package with   and   options for precaution:

Remove the package using the dependency sensitive   option instead of   which may remove important packages:

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
Since version 2.3.0 is packaged separately  from Portage. See the article for additional 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 is occurs 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 possible to be caused by the reasons listed in the output above, this issue is more likely 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:

Next, use the command to view the disk space in the partition where PORTAGE_TMPDIR has been mounted. For Handbook formatted systems this will likely be the root partition. See Freeing disk space for details on how to free up disk space.