Portage
Portage is a very advanced package manager that will treat the user's wishes with the highest respect. Sometimes too much trust in put into the user, so you may be looking for Portage Help rather than this article.
Portage is the official package manager and distribution system for Gentoo. It functions as the heart of Gentoo-based operating systems, providing advanced dependency resolution, flexible building and installation of software from source or from binary packages, and most other core distribution functionality.
Portage will provision software from the Gentoo ebuild repository, any additional ebuild repositories, or binhost. Portage includes many commands for repository and package management, the primary of which is the emerge command.
Some common questions about portage and the emerge command are answered in the FAQ and the Portage FAQ.
For day to day usage, the emerge, emaint, and dispatch-conf will be the most used Portage commands. Refer to relevant documentation.
See man portage for complete user documentation. See the emerge article for information on installing and maintaining packages with Portage.
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, so there is no need to install it!.
In the rare eventuality of a corrupt or missing Portage, see the Corrupt or absent Portage section.
Updating 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 advisable to update Portage before the rest of the system. After synchronizing Portage, a message requesting this may be displayed:
* 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.
Configuration
Files
The main Portage configuration is in make.conf, though there are many files used to configure Portage, mainly in the /etc/portage directory.
See man make.conf for comprehensive documentation, notably a list of variables that can be set in this file.
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 make.conf for information on available environment variables. Refer also to 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, for example:
- 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, and the GURU repository has some developer oversight, 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.
Binary hosts
Binary hosts are configured in /etc/portage/binrepos.conf and allow fast installation of binary packages, as long as there is a package available for the requested USE flags for the package being installed or updated.
There is an official Gentoo binary host that contains many binary packages for the amd64 and arm64 architectures - see the guide at that link for further setup and usage instructions.
To configure alternative binary hosts, and for more information on using binary packages with Portage, see the binary package guide.
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 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
dispatch-conf
The dispatch-conf utility is used to manage configuration file updates. See the dispatch-conf article.
ebuild
This section covers the ebuild command. For information on ebuild files, see the ebuild article.
As a user, do not use the ebuild command to install packages. The ebuild command is provided mainly for package development, use the emerge command to install packages.
ebuild is Portage's command for running the various ebuild functions.
For a brief summary of usage and command-line options:
root #
ebuild --help
For more information on the ebuild command, view it's man page:
user $
man 1 ebuild
egencache
The egencache 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 emaint to synchronize repositories. See man 1 emaint for detailed information.
user $
emaint --help
emerge
emerge is the command-line interface to Portage and is how most users will interact with Portage.
See the emerge article for more information on the wiki.
emerge-webrsync
Install a Gentoo ebuild repository snapshot from the web. See Handbook.
root #
emerge-webrsync -h
emerge-webrsync is called internally by eix-sync when sync-type
in /etc/portage/repos.conf is set to webrsync
.
emirrordist
Tool for mirroring of package distfiles.
root #
emirrordist -h
See also man emirrordist.
env-update
Updates environment settings automatically.
root #
env-update -h
See also man env-update. See the login article for some information on how the environment is set up in Gentoo.
etc-update
dispatch-conf is the recommended way to manage configuration file changes. Using etc-update risks the loss of important data.
See the etc-update article.
fixpackages
Perform package move updates for all packages.
root #
fixpackages -h
See also man fixpackages.
glsa-check
Gentoo Linux Security Announcements, or GLSAs, are notifications sent out to the community to inform of security vulnerabilities related broadly to Gentoo Linux or specifically to packages contained in the ::gentoo ebuild 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
gpkg-sign
Todo:
- This section needs an explanation on the use of this command.
user $
gpkg-sign --help
portageq
For details see portageq.
quickpkg
This command uses the current state of files present on the system, which is often not what is desired when creating binary packages. See the quikpkg section of the Binary package guide for more information.
Creates binary packages using the current state of files present on the system. See the quikpkg section of the Binary package guide for more information.
user $
quickpkg --help
See also man quickpkg.
regenworld
See the regenworld article.
repoman
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.
It is now deprecated in favor of tools provided by the dev-util/pkgcheck and dev-util/pkgdev packages.
Tips
Common portage issues and resolutions
Gentoo has many more configuration options than most distributions allow. This leads to some confusing at first terminology, such as blockers, Circular dependencies, REQUIRED_USE and some others.
The articles linked below, will help a user understand how they come about and how to resolve them.
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
Listing package sets
Need to determine what packages are inside each set? See Package sets.
Troubleshooting
Corrupt or absent Portage
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.
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
repo_basedir="/usr"
repo_name="portage"
distdir="/usr/portage/distfiles"
portdir="/usr/portage"
target_distdir="/usr/portage/distfiles"
target_pkgdir="/usr/portage/packages"
New location
repo_basedir="/var/db/repos"
repo_name="gentoo"
distdir="/var/cache/distfiles"
portdir="/var/db/repos/gentoo"
target_distdir="/var/cache/distfiles"
target_pkgdir="/var/cache/binpkgs"
See also
- /etc/portage — the primary configuration directory for Portage, Gentoo's package manager.
- /etc/portage/make.conf — the main configuration file used to customize the Portage environment on a global level., the location Portage keeps binary packages.
- /etc/portage/color.map — a file containing variables that define color classes used by Portage.
- prefix — enables the power of Gentoo and Portage on other distributions and/or operating systems (Microsoft Windows via Cygwin, Android via Termux, etc.).
Related to Portage
- Upgrading Gentoo — explains how to upgrade (update) Gentoo, as well as how to proceed for a well maintained system.
- Catalyst — a tool to build stage files and live-images for 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 — the main command-line interface to Portage
- 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 — It is unlikely that tmpfs will provide any performance gain for modern systems
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
Portage tools
- Useful Portage tools — provides a list of Gentoo-specific system management tools, notably for Portage, available in the ebuild repository.
- Cfg-update — a utility used on Gentoo to manage configuration file updates.
Alternate package managers and GUIs
- Pkgcore — an alternative package manager for Gentoo that aims for high performance, extensibility, and a clean design.
- app-portage/kuroo - Graphical Portage frontend based on KF5/Qt5.
- App Swipe - Qt GUI for browsing local Portage repositories.
- Package sets — describes package sets in high detail and includes a list of all typically available sets on a Gentoo system.
External resources
- Official Portage documentation - Built by Portage developer Zac Medico (zmedico) .
- 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.
- emerge - command-line interface to the Portage system - emerge man page.
- Portage configuration files - Portage man page.