From Gentoo Wiki
Jump to: navigation, search
This article is a stub. You can help Gentoo Wiki by expanding it.

Portage is the package management and distribution system for Gentoo. It essentially functions as the heart of Gentoo and Gentoo-based operating systems.


All Gentoo installations come with Portage. There are times where Portage can become corrupted, which is very bad. In this case there are ways Portage can be recovered, however Portage re-installation can be a hassle and just be mostly performed by booting a minimal install cd.

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 buildpkg Portage feature on a healthy machine or by using the quickpkg command (see the binary package guide).

Manually build Portage

Manually download a copy of a recent Portage release via tarball, build it, and manually install it. The administrator will have to perform all the work that Portage world normally automate. This option could be easier than the first option, and may potentially take less time.

  1. Boot up a LiveDVD/CD that has Portage included (Gentoo LiveDVDs or SystemRescueCD should contain Portage). Remove the old or broken Portage and reinstall install 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 /mnt/gentoo 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 /mnt/gentoo, the command would look like this:
      root #DISTDIR="/mnt/gentoo/usr/portage/distfiles" PKGDIR="/mnt/gentoo/usr/portage/packages" PORTAGE_CONFIGROOT="/mnt/gentoo/" PORTAGE_TMPDIR="/mnt/gentoo/var/tmp" PORTDIR="/mnt/gentoo/usr/portage"
    2. Run the emerge command in order to remove any traces of the old broken Portage package:
      root #emerge -C sys-apps/portage
    3. Sync the Portage Tree in case the system is a bit behind on the current Portage tree:
      root #emerge --sync
    4. Install the new version of Portage:
      root #emerge -uN sys-apps/portage


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

CODE Portage update message
* 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 portage' now.
root #emerge --oneshot sys-apps/portage

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



In addition to the official repository (colloquially known as the "Portage Tree" because of its traditional placement in /usr/portage/), there are additional repositories which in Gentoo called overlays.

It is possible to search through the ebuilds available in the overlays on http://overlays.gentoo.org/ by using the eix tool.

GUI front-ends

There are a few GUI interfaces that exist for Portage, although some of them have become unmaintained.

Name Package Homepage Maintained? Description
kport Unavailable http://kport.sourceforge.net/ No A GUI frontend for the Portage package management system.
kuroo app-portage/kuroo4 http://sourceforge.net/projects/kuroo/ Yes Graphical Portage frontend based on KDE4/Qt4.
porthole app-portage/porthole http://porthole.sourceforge.net/ Yes A GTK+-based frontend to Portage.



emerge is the command-line interface to the Portage system. This 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 you see an exemplary invocation of emerge. The options (-atv) are shortcuts 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. 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."

# 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]

Common invocations

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

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

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

Remove the net-proxy/tinyproxy package using the dependency sensitive --depclean option instead of --unmerge which may remove important packages:

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

See also

Alternate package managers:

  • Paludis - An alternative package manager written expressly for Gentoo-based systems.
  • Pkgcore - A framework for package management, mostly compatible with Gentoo
  • app-arch/dpkg - A package manager for Debian based systems.
  • sys-apps/yum - The package manager for RPM systems that also can be used on Gentoo.

Related to Portage:

Portage in the Gentoo AMD64 Handbook:

Portage tools