From Gentoo Wiki
Jump to: navigation, search
Other languages:
English • ‎français • ‎日本語 • ‎한국어

An overlay is an additional repository that Portage takes into account when dealing with software.

Within Gentoo Linux, users already have one "main" package repository, called the Portage Tree. This main repository contains all the software packages (called ebuilds) maintained by Gentoo developers. But users can add additional repositories to the tree that are "layed over" the main tree - hence the name, overlays.

Since package repositories are nothing more (or less) than a set of files (ebuilds, metadata files, ChangeLog entries ...) these repositories can be pulled in from public repositories (git, cvs, svn ...) or downloaded as tarballs and extracted manually onto the system. It is advised to use managed repositories by trusted third parties; any installed overlay will cause Portage to look through the overlayed files when deciding which software to install. If compromised code is in the overlay, then compromised packages could be installed on the system.

Treatment of overlays

Portage uses the PORTDIR_OVERLAY variable to link to the installed overlays on the system. This variable uses a space-delimited list of paths on the system where Portage can find the roots of the additional repositories.

Manually setting overlay locations

To make a personal overlay, create a location (/usr/local/myportage for example) in which the packages Portage is to look for are located. Then add the PORTDIR_OVERLAY variable to the /etc/portage/make.conf file containing the path to the location of the custom overlay.

FILE /etc/portage/make.conf Example 1 - Adding a custom overlay

An example of an overlay being located in the a user's home directory:

FILE /etc/portage/make.conf Example 2 - Adding a custom overlay
PORTDIR_OVERLAY="/home/user/overlay" # requires /home is readable for Portage

Add user to Portage group

To add a user to the portage group, use the gpasswd command like so:

root #gpasswd -a larry portage

See also adding a user to a group.

Using crossdev

crossdev will automatically place the ebuilds/categories it generates into the first overlay found in PORTDIR_OVERLAY. Most users will want to prevent crossdev from disturbing layman's overlays or the user's personal per-machine overlay (normally created at /usr/local/portage). Create an overlay specifically for crossdev's use:

root #mkdir -p /usr/local/portage-crossdev/profiles
root #echo local-crossdev > /usr/local/portage-crossdev/profiles/repo_name

Then instruct portage and crossdev to use this overlay:

FILE /etc/portage/make.conf Let crossdev to store its ebuild in local-crossdev and indicate that the local overlay should override every other overlay
source /var/lib/layman/make.conf
PORTDIR_OVERLAY="/usr/local/portage-crossdev ${PORTDIR_OVERLAY} /usr/local/portage"
FILE /etc/portage/make.conf Prevent crossdev from messing with the local overlay when not using layman
PORTDIR_OVERLAY="/usr/local/portage-crossdev /usr/local/portage"

Using layman

To make management of multiple overlays simple, a tool called layman is developed. This tool knows about popular user- and developer managed overlays and is able to install & synchronize them as well as add them to the PORTDIR_OVERLAY location.

Local overlay

For instructions on setting up a local overlay, see Overlay/Local_overlay.

Overlay priorities

Each overlay has its unique priority. This makes sure that in the case of a specific version being found in several overlays, the resolution is unambiguous. Ebuilds from overlays with higher priorities take precedence over ebuilds from overlays with lower priorities.

This "natural" way of priority handling was introduced in January 2011, before that the priority resolution order was reversed, so negative numbers used to stand for high priorities

The list of overlays with their priorities can be obtained through the output of the following command

user $emerge --info --verbose

Unless the PORTDIR_OVERLAY variable has been modified as described below, the default gentoo portage tree will have a priority of -1000. That means that all other overlays take precedence. That is the default behavior, because overlays are designed to "lay over/on top" of the portage tree.

Setting overlay priorities

The overlay priority is calculated from the order of overlay entries in the PORTDIR_OVERLAY variable. Portage "walks" through the variable from left to right and increments the priority on the way. The leftmost entry starts with a priority of 1, the next entry has a priority of 2 and so on.

Some time ago the overlay priority could be set in /etc/portage/repos.conf. This does not work anymore

Unless the PORTDIR_OVERLAY contains the portage tree entry, the portage tree will always be assigned a priority of -1000. This can be easily changed by putting PORTDIR in the PORTDIR_OVERLAY variable:

FILE /etc/portage/make.conf Manual portage tree priority setting
PORTDIR_OVERLAY="/home/user/overlay ${PORTDIR}"

In the example above the user overlay will be assigned a priority of 1 and the portage tree will be assigned a priority of 2.

If layman is used to manage overlays, then please refer to the article about setting overlay priorities with layman.

Using unsafe overlays

When using huge overlays or those with unknown/low quality it is best practice to hardmask the whole overlay.

FILE /etc/portage/package.mask Mask all packages in an overlay

After that unmask the packages that will be installed.

FILE /etc/portage/package.unmask Unmask a specific package in an overlay

This way nothing weird will happen on updates and it is safer than using priorities.

Metadata cache

Cache generation

When large overlays are installed, portage may take a long time to perform operations like dependency resolution. This is because overlays do not usually contain a metadata cache.

Generate a local metadata cache by running emerge --regen after syncing the overlays:

root #layman -S
root #emerge --regen

Be careful, because emerge --regen takes a lot of time and it's not recommended for rsync users as rsync updates the cache using server-side caches (most of users of portage are rsync users). Rsync users should simply run emerge --sync (or eix-sync) to regenerate the cache. It's probably only users of very large overlays should try emerge --regen.

eix integration


eix-sync can run emerge --regen after syncing the overlays and portage tree.

FILE /etc/eix-sync.conf
# Sync all overlays
# Regenerate overlay metadata
@emerge --regen || true


eix-update can utilize the metadata cache generated by emerge --regen for a speedup and better accuracy. To enable this, set the OVERLAY_CACHE_METHOD to assign in /etc/eixrc/01-cache.

FILE /etc/eixrc/01-cache Setting OVERLAY_CACHE_METHOD