The portage holds all ebuilds maintained and tested by the Gentoo developers but there is also a need to develop and test ebuilds outside of the regular tree. If ebuild modifications would be done inside the /usr/portage directory, the changes would be wiped out after emerge --sync. Therefore such ebuilds have to be put in Overlays (as found at https://overlays.gentoo.org/ or http://gpo.zugaina.org/.

There is an old and simple way via PORT_OVERLAY variable in /etc/portage/make.conf note also the program layman uses it.

There is a new and preferred way via repositories defined in the /etc/portage/repos.conf directory. In this case the term overlay appears to be not correct since the ebuilds are added as the standard ebuilds in the /usr/portage directory. In this case the proper term is repository. Overlay and repository directories can have identical files, just they way how the got used by the system makes the difference. Therefore the following uses the term Overlay also for such a directory containing ebuilds.


Using Overlays could result that the same ebuilds could be found more then ones. If this is the case then emerge complains. However this applies just for the ebuild files not for the directories or the Manifest files. So overlapping might be useful when developing ebuilds.


To be more open, overlays can be handled exactly the same way as /usr/portage using the repository configuration found in /etc/portage/repos.conf. As example and consequence the file gentoo.conf holds all necessary to get the the standard gentoo ebuilds.

Instead adding manually a config file emerge eselect-repository


Run eselect repository list first to set it up

eselect repository add linursoverlay git https://github.com/linurs/linursoverlay.git creates then a config file eselect-repo.conf that holds all necessary to find as example the linursoverlay from GitHub. It creates the local copy in /var/db/repos

emerge --sync or faster emerge --sync linursoverlay will then get the updates


Working with repositories does not require layman and also no layman configuration. layman -L will not show those repositories, layman -S will not synchronize them and layman -a will not add them.

Local overlay directories

Local overlays are mainly used to develop ebuilds.

Create a local overlay directory where the collection of ebuilds go:

mkdir<path to overlay directory>>

Tell /etc/portage/make.conf where it is by adding the following line

PORTDIR_OVERLAY="<path to first overlay directory> <path to second overlay directory>"

Now additional sub-directories serving as categories (as app-editors) can be created there where the ebuilds to be developed can be put.


A profiles and metadata subdirectory should exist. For other examples check existing overlays as found in /var/lib/layman, /usr/portage, https://github.com/linurs/linursoverlay or read the gentoo manual.

Now let your console know what you did:

source /etc/portage/make.conf

And verify the result:


Now you can work in this console with your local overlay. Since every process has it own environmental variables, just this console and its children will have the PORTDIR_OVERLAY variable updated.


The tool layman (emerge layman) handles overlays via expanding the PORTDIR_OVERLAY variable. layman can be considered outdated since adding repositories is the new way.

To see what overlays layman can get

layman -L

To add a single overlay out of the list of available overlays:

layman -a<overlay-name>

As example layman -a sunrise

To see what overlays you have installed

layman -l

To de-install

layman -d <overlay-name>

To install a package from the overlay (= ebuild)

emerge -av<category>/<package>

To update the overlays

layman -s <overlay name>


layman -s ALL


layman -S


Overlays can also mask packages. Therefore look to directories as:


To unmask the files edit /etc/portage/package.unmask and if they are unstable unmask them in /etc/potrage/package.keywords

layman creates a cache under /var/lib/layman


After emerge --unmerge layman this cache remains and must be deleted manually rm -fr /var/lib/layman

/etc/layman/layman.cfg is the configuration file.

Overlays in GitHub

Overlays can be put in GitHub and therefore be used by many computers.

A GitHub account is required that has a name. GitHub uses also the term repository to hold the files. A GitHub repository needs therefore to be created that holds the overlay or repository.

In this GitHub repository the the required ebuilds need to be put. Take an already existing overlay as example and create a directory with the ebuilds and the metadata and profiles directory.

Inside this directory add a repository.xml file needs to be added that holds all the necessary data about the overlay/repository.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
<repo quality="experimental" status="unofficial">
      experimental ebuilds from linurs.org
    <owner type="person">
        <name>Urs Lindegger</name>
    <source type="git">
    <source type="git">

To update it follow the GitHub rules and create a branch, so master branch stays intact for all the other users. When done create a pull request followed by a merge to the master.

The GitHub repository can be added to a Gentoo system as repositories or the old way as overlays.

xmllint --noout --schema $(portageq get_repo_path / gentoo)/metadata/xml-schema/repositories.xsd repositories.xml or

xmllint --noout --schema /usr/portage/metadata/xml-schema/repositories.xsd repositories.xml

verifies the repositories.xml file. See for other things missing: https://wiki.gentoo.org/wiki/Project:Overlays/Overlays_guide

to clone it git clone https://github.com/gentoo/api-gentoo-org.git

cd api-gentoo-org/

Add the repository to files/overlay/repositories.xml and then the tricky authorization part starts to push it back and make a pull request.

Eix search in not installed overlays

Commands as emerge --search, esearch or gui programs as porthole will find the ebuilds in the installed overlays. However there are many overlays not installed and it makes no sense to install all available overlays just to look for an ebuild that might or not might be there. To get a tool that can search in not installed overlays emerge eix

eix is much more than just an overlay search tool, it is an alternative to various gentoo tools. Therefore it has a

There is a huge list of options as man eix shows. eix-update will update is cache containing portage and the installed overlays.

The command eix-remote update will download the /var/cache/eix/remote.tar.bz2 file and than unpack it, it is quite common that this file has a newer version than eix being used and then fails. In this case simply update eix to the newest version.

Per default eix-update will rewrite the cache and therefore delete what eix-remote update added. To avoid that a variable needs to be set check if eix --dump | grep KEEP_VIRTUALS. As default it reports false, so the following needs to be added to /etc/eixrc then it has to be added


Finally to look for a ebuild type eix<ebuildname>.

Linurs startpage