Ebuild repository

An ebuild repository is Article description::a file-structure that provides packages for a Gentoo system. Ebuild repositories contain ebuilds, eclasses, and other types of descriptive metadata files that inform Portage of software available for installation, news items, profile targets, etc.

The Gentoo ebuild repository, Gentoo project's primary and official ebuild repository, is the source for all the information needed to build and install Gentoo packages.

As well as providing new packages, an active ebuild repository can replace packages from the Gentoo ebuild repository - with newer or alternative versions for example - if they provide packages that already exist in the Gentoo repository. According to a set order of priority, active ebuild repositories can also replace packages from other ebuild repositories - hence the colloquial name overlay.

Administrators of Gentoo systems can add additional ebuild repositories by using the utilities and methods described below.

The Gentoo ebuild repository
The Gentoo ebuild repository is the primary ebuild repository of a Gentoo system, usually where all the packages come from. It is hosted and maintained on the gitweb.gentoo.org Gentoo server, and gets synchronized to local machines, to be available to Portage.

The Gentoo ebuild repository contains ebuild files that tell Portage how to build each package that makes up an "official" Gentoo installation. These ebuilds describe all the software available for installation, with metadata, dependency info and everything else needed for installation. The metadata provides the package's name, version, available USE flags, license, website etc.

Dependency information in ebuilds allows Portage to pull in any other packages required to build and run whatever is to be installed - no more, no less. Dependencies are very granular in Gentoo. Where many other distributions would have one large dependency, Gentoo will cut them up into elemental units, so as to pull in only the parts that are really required. On the surface this may make dependencies seem more numerous, but the packages on the disk will take up no more space for this, and it allows to install even less code - only what is absolutely needed. Dependencies will even vary depending on what use flags are selected, for ultimate selectivity.

Perhaps most importantly, the ebuilds contain the information required to configure, build (compile), install, and test each package, usually from a project's own source code.

In addition to the ebuilds, the Gentoo ebuild repository contains the official profiles, which define the default state of USE flags, default values for most variables found in, the set of system packages, and select available package versions that define what packages are available for a given architecture.

The Gentoo ebuild repository is also the place where the news items are provided, which is why any new news items will be highlighted after a Gentoo ebuild repository synchronization.

The Gentoo ebuild repository, and it's ebuilds, are maintained by the Gentoo developers and other members of the community.

Where do ebuild repositories come from ?
Because an ebuild repository is simply a structure of files and directories, a new ebuild repository can be made available to Portage simply by copying those files and directories to a location known to Portage. The location of repositories configured for Portage is specified in /etc/portage/repos.conf, and the actual ebuild repository and it's files are usually under. Ebuild repositories can be configured on any accessible filesystem however, even on an nfs or SSHFS filesystem - allowing them to be stored on a network or Internet server.

As previously discussed, the Gentoo ebuild repository is hosted on gitweb.gentoo.org. That server also hosts other ebuild repositories.

In practice, except for maybe private and personal use, any additional ebuild repositories aren't just copied to a directory by hand and configured for Portage (meaning added to /etc/portage/repos.conf). Generally, new repositories are made available by third parties, and once configured for Portage, are synchronized by Portage. Synchronization copies all the files from a central remote location to the configured location on a locally available filesystem - in the case of the first synchronization - or updates the files from the remote location on subsequent synchronizations.

Because ebuild repositories are just file-structures, many methods can be used to synchronize them, and Portage offers several methods. Rsync is the default synchronization method, git is also popular. The synchronization method is specified in /etc/portage/repos.conf when configuring a repository, along with the information needed to retrieve it, for an rsync or git based repository.

Publicly available repositories can be registered on repos.gentoo.org for easy configuration with the management tools.

Repository management
Use the Eselect/Repository tool to easily add, disable, or remove ebuild repositories configured with Portage. This tool also provides a handy way to list and add repositories available through being registered on repos.gentoo.org.

New ebuild repositories for use with Portage can also be created by the user.

Ebuild repositories can always be configured by editing manually.

Layman can still be used to manage repositories, but it is superseded by for most uses.

Installing packages from other repositories
Packages from repositories other than the Gentoo ebuild repository can be installed with the command, just as always:

For example, once the GURU repository is added, to install the x11-misc/xbanish package from that repository:

Note that the repository is not specified in the command. The "::guru" appended to the package atom shows what repository the package will be installed from. This works because the x11-misc/xbanish package is present in the GURU repository, but not in the Gentoo repository.

If multiple versions of the same package are available from two or more different ebuild repositories, Portage will install the most recent version.

If the latest version of a package is available from more than one ebuild repository, the repository with the highest priority will be used. The priority can be set for an ebuild repository in /etc/portage/repos.conf. The Gentoo ebuild repository has a default priority set to, and the default if priority is not set is. If several ebuild repositories have the same priority (such as two or more not having a priority set, so having priority ), the order is undetermined - a package to install will be chosen arbitrarily.

It is possible to instruct Portage to install a package from a specific ebuild repository with the  version specifier:

The same notation can be used for different emerge instructions, including uninstalling a package through.

The list of active ebuild repositories with their priorities can be obtained through the output of one of the following commands:

Repository synchronization
Ebuild repositories should be updated, aka synchronized, so that local copies will reflect a recent state of the parent repositories, to be able to keep the system up to date, and install current software. Regularly synchronizing with the Gentoo repository and updating the system in this way is important, to ensure that all the latest security updates are installed, and that the local system does not get too out of sync with the Gentoo repository, as this can make upgrades complicated.

Synchronization for each repository is configured through the files in.

Repository synchronization is managed with the command:

To sync all repositories for which  is set, run  with the   switch (  for short). This is usually the command that should be run regularly, before system updates and package installation (and is equivalent to using the old command):

To sync the foo repository (irrespective of the foo auto-sync setting):

To sync all repositories with a valid sync-type and sync-url defined. (ignoring auto-sync settings):

See for information on how to use the portage synchronization commands. See the Portage project sync article about migrating to the new modular sync system from Portage version 2.2.16, it contains important information, notably for users of, , and.

Cache generation
When large ebuild repositories are installed, Portage may take a long time to perform operations like dependency resolution. This is because ebuild repositories do not usually contain a metadata cache.

Generate a local metadata cache by running after syncing the ebuild repositories:

Be careful, because 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 (or ) to regenerate the cache. It's probably only users of very large ebuild repositories should try.

Masking enabled ebuild repositories
When using large ebuild repositories or those with unknown/low quality code, it is best practice to hard mask the whole ebuild repository and only accept specific ebuilds on a case-by-case basis. For example, for an overlay named "repository-foobar":

Then add the specific package(s) from the repository-foobar overlay so that they will be available visible to Portage for installation:

After the above unmask the package named "foo-category/bar" should be available and none of the other packages from the repository-foobar overlay will be available, which is by design.

External resources

 * https://repos.gentoo.org - Gentoo's official ebuild repository hosting location.
 * https://github.com/gentoo/ - GitHub mirror of the Gentoo's ebuild repository.
 * https://gpo.zugaina.org/Overlays - A non-official very useful site for searching overlays.