Portage

Resources

Portage is the official package management and distribution system for Gentoo. It essentially functions as the heart of Gentoo-based operating systems. Portage includes many commands for repository and package management, the primary of which is the emerge command.

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

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 the 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 buildpkg Portage feature on a healthy machine or by using the quickpkg 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 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 --ask --unmerge 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 --ask --update --newuse sys-apps/portage

Tarball

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

user $

wget https://github.com/gentoo/portage/archive/v2.2.22.tar.gz -O portage-2.2.22.tar.gz

user $

tar --extract --gz --verbose --file portage-2.2.22.tar.gz

user $

cd portage-2.2.22

Install via setup.py:

root #python setup.py install

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

root #

echo "portage:x:250:250:portage:/var/tmp/portage:/bin/false" >> /etc/passwd

root #

echo "portage::250:portage" >> /etc/group

Create the /usr/portage directory if it does not exist:

root #mkdir /usr/portage

Updating

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 --ask --oneshot sys-apps/portage

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

Configuration

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:

Warning
This page is a work in progress by maffblaster (talk | contribs). Treat its contents with caution.

Overlays

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/	No (2014)	Graphical Portage frontend based on KDE4/Qt4.
porthole	app-portage/porthole	http://porthole.sourceforge.net/	No (2010)	A GTK+-based frontend to Portage.

Usage

archive-conf

dispatch-conf

See the dispatch-conf article.

ebuild

See the ebuild article.

egencache

See the egencache article for additional information.

emaint

See Project:Portage/Sync#Operation and man 1 emaint.

emerge

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

emerge-webrsync

root #emerge-webrsync -h

Usage: /usr/bin/emerge-webrsync [options]

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!)

emirrordist

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

Actions:
  --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)
  --ignore-default-opts
                        do not use the EMIRRORDIST_DEFAULT_OPTS environment
                        variable
  --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
                        repos.conf)
  --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
                        fetching
  --restrict-mirror-exemptions RESTRICT_MIRROR_EXEMPTIONS
                        comma delimited list of mirror targets for which to
                        ignore RESTRICT="mirror"
  --verify-existing-digest
                        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

env-update

root #env-update -h

Usage: env-update [--no-ldconfig]

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

etc-update

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.

Options:
  -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'

fixpackages

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

regenworld

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.

portageq

root #portageq -h

>>> Portage information query tool
>>> 2.2.28
>>> Usage: portageq <command> [<option> ...]

Available commands:
   all_best_visible <eroot>
      Returns all best_visible packages (without .ebuild).
   available_eclasses <eroot> <repo_id>+
      Returns space-separated list of available eclasses for specified repository.
   best_version <eroot> <category/package>
      Returns highest installed matching category/package-version (without .ebuild).
   best_visible <eroot> [pkgtype] <atom>
      Returns category/package-version (without .ebuild).
      The pkgtype argument defaults to "ebuild" if unspecified,
      otherwise it must be one of ebuild, binary, or installed.
   colormap Display the color.map as environment variables.
   config_protect Returns the CONFIG_PROTECT paths.
   config_protect_mask Returns the CONFIG_PROTECT_MASK paths.
   contents <eroot> <category/package>
      List the files that are installed for a given package, with
      one file listed on each line. All file names will begin with
      <eroot>.
   distdir Returns the DISTDIR path.
   eclass_path <eroot> <repo_id> <eclass>+
      Returns the path to specified eclass for specified repository.
   envvar <variable>+
      Returns a specific environment variable as exists prior to ebuild.sh.
      Similar to: emerge --verbose --info | egrep '^<variable>='
   expand_virtual <eroot> <atom>
      Returns a \n separated list of atoms expanded from a
      given virtual atom (GLEP 37 virtuals only),
      excluding blocker atoms. Satisfied
      virtual atoms are not included in the output, since
      they are expanded to real atoms which are displayed.
      Unsatisfied virtual atoms are displayed without
      any expansion. The "match" command can be used to
      resolve the returned atoms to specific installed
      packages.
   filter_protected <eroot>
      Read filenames from stdin and write them to stdout if they are protected.
      All filenames are delimited by \n and must begin with <eroot>.
   gentoo_mirrors Returns the mirrors set to use in the portage configuration.
   get_repo_path <eroot> <repo_id>+
      Returns the path to the repo named argv[1], argv[0] = $EROOT
   get_repos <eroot>
      Returns all repos with names (repo_name file) argv[0] = $EROOT
   has_version <eroot> <category/package>
      Return code 0 if it's available, 1 otherwise.
   is_protected <eroot> <filename>
      Given a single filename, return code 0 if it's protected, 1 otherwise.
      The filename must begin with <eroot>.
   license_path <eroot> <repo_id> <license>+
      Returns the path to specified license for specified repository.
   list_preserved_libs <eroot>
      Print a list of libraries preserved during a package update in the form
      package: path. Returns 1 if no preserved libraries could be found,
      0 otherwise.
   mass_best_version <eroot> [<category/package>]+
      Returns category/package-version (without .ebuild).
   mass_best_visible <eroot> [<type>] [<category/package>]+
      Returns category/package-version (without .ebuild).
      The pkgtype argument defaults to "ebuild" if unspecified,
      otherwise it must be one of ebuild, binary, or installed.
   master_repos <eroot> <repo_id>+
      This is an alias for the master_repositories command.
   master_repositories <eroot> <repo_id>+
      Returns space-separated list of master repositories for specified repository.
   match <eroot> <atom>
      Returns a \n separated list of category/package-version.
      When given an empty string, all installed packages will
      be listed.
   metadata <eroot> <pkgtype> <category/package> [<key>]+
      Returns metadata values for the specified package.
      Available keys: DEFINED_PHASES,DEPEND,DESCRIPTION,EAPI,HDEPEND,HOMEPAGE,INHERITED,IUSE,KEYWORDS,LICENSE,PDEPEND,PROPERTIES,PROVIDE,RDEPEND,REQUIRED_USE,RESTRICT,SLOT,SRC_URI
   owners <eroot> [<filename>]+
      Given a list of files, print the packages that own the files and which
      files belong to each package. Files owned by a package are listed on
      the lines below it, indented by a single tab character (\t). All file
      paths must either start with <eroot> or be a basename alone.
      Returns 1 if no owners could be found, and 0 otherwise.
   pkgdir Returns the PKGDIR path.
   portdir Returns the PORTDIR path.
      Deprecated in favor of get_repo_path command.
   portdir_overlay Returns the PORTDIR_OVERLAY path.
      Deprecated in favor of get_repos & get_repo_path or repos_config commands.
   pquery [options] [atom]+
      Emulates a subset of Pkgcore's pquery tool.
   repos_config <eroot>
      This is an alias for the repositories_configuration command.
   repositories_configuration <eroot>
      Returns the configuration of repositories.
   vdb_path Returns the path used for the var(installed) package database for the
      set environment/configuration options.

Pkgcore pquery compatible options:

usage: portageq pquery [options] [atom ...]

Repository matching options:
  --no-filters          no visibility filters (ACCEPT_KEYWORDS, package
                        masking, etc)
  --repo REPO           repository to use (all repositories are used by
                        default)

Package matching options:
  --maintainer-email MAINTAINER_EMAIL
                        comma-separated list of maintainer email regexes to
                        search for
  --orphaned            match only orphaned (maintainer-needed) packages

Output formatting:
  -n, --no-version      collapse multiple matching versions together

quickpkg

See the Binary package guide for more information.

repoman

Note
Since version 2.3.0 repoman is no longer part of Portage and has its own ebuild and release package

See the repoman article for additional information.

Portage

Contents

Installation

Binary package

Tarball

Updating

Configuration

Files

Environment variables

Overlays

GUI front-ends

Usage

archive-conf

dispatch-conf

ebuild

egencache

emaint

emerge

Common invocations

emerge-webrsync

emirrordist

env-update

etc-update

fixpackages

regenworld

portageq

quickpkg

repoman

See also