Portage
Portage is the official 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 emerge command.
The most common questions about portage and the emerge command are handled in the Portage FAQ.
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 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 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 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 /mnt/gentoo the following commands could be used from a live environment.
- 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/var/cache/distfiles" PKGDIR="/mnt/gentoo/var/cache/binpkgs" PORTAGE_CONFIGROOT="/mnt/gentoo/" PORTAGE_TMPDIR="/mnt/gentoo/var/tmp" PORTDIR="/mnt/gentoo/var/db/repos/gentoo"
- Run the emerge command in order to remove any traces of the old broken Portage package:
root #
emerge --ask --unmerge sys-apps/portage
- Sync the system in case it is a bit behind on the current Gentoo repository:
root #
emerge --sync
- 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.x.xx.tar.gz -O portage-2.x.xx.tar.gz
user $
tar --extract --gz --verbose --file portage-2.x.xx.tar.gz
user $
cd portage-2.x.xx
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 /var/db/repos/gentoo directory if it does not exist:
root #
mkdir /var/db/repos/gentoo
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.
|* 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 -u1 sys-apps/portage
This is short hand expression for:
root #
emerge --ask --oneshot --update 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:
This page is a work in progress by maffblaster (talk | contribs). Treat its contents with caution.
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.
Graphical front-ends
Name | Package | Homepage | Maintained | Description |
---|---|---|---|---|
kuroo | app-portage/kuroo | https://sourceforge.net/projects/kuroo/ | Yes | Graphical Portage frontend based on KF5/Qt5. |
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
Usage: archive-conf /CONFIG/FILE [/CONFIG/FILE...]
dispatch-conf
The dispatch-conf utility is used to manage configuration file updates. See the dispatch-conf article.
ebuild
ebuild is Portage's command for running the various ebuild functions. For disambiguation see the ebuild article.
egencache
The egencache tool rebuilds the cache of metadata information for the ebuild repositories. See the egencache article for additional information.
emaint
Implements the emerge --sync command. See Portage's 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 short options 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."
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
Verifying and (re)downloading distfiles
To re-verify the integrity of and re-download previously removed/corrupted distfiles for all currently installed packages, run:
root #
emerge --ask --fetchonly --emptytree @world
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!)
emerge-webrsync is called internally by eix-sync when sync-type
in /etc/portage/repos.conf is set to webrsync
.
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
For details see portageq.
quickpkg
See the Binary package guide for more information.
repoman
Since version 2.3.0 repoman is packaged separately (app-portage/repoman) from Portage. See the repoman article for additional information.
Troubleshooting
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
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:
user $
portageq envvar PORTAGE_TMPDIR
/var/tmp
Next, use the df 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.
See also
- /etc/portage — the primary configuration directory for Portage, Gentoo's package manager.
Alternate package managers:
- Pkgcore — an alternative package manager for Gentoo that aims for high performance, extensibility, and a clean design.
- app-arch/dpkg - A package manager for Debian based systems.
Related to Portage:
- GCC optimization — an introduction to optimizing compiled code using safe, sane CFLAGS and CXXFLAGS.
- Portage tips — contains a list of tips for Portage users
- 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 structure of directories and files used to add and extend software packages for a Gentoo-based system.
- Category:Portage
- Gentoolkit — a suite of tools to ease the administration of a Gentoo system.
- 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 — Building packages in tmpfs both speeds up emerge times and reduces HDD/SSD wear.
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 — a list of helpful Portage-related tools.
- Cfg-update — a utility used on Gentoo to manage configuration file updates.