Stepping aside from the official tree

Updated 13 August 2019

Using your own Portage tree

Excluding a package or a category

You can update your software in a selective manner, ignoring the category/package updates that you do no need. This is achieved by excluding those categories/packages from the rsync routine when running emerge --sync.

To do so, you need to specify, in RSYNC_EXCLUDEFROM, the file containing the templates of the excluded package:



As an example, let's exclude all games:


exec "games-*/*

Note, though, that this can lead to dependency problems, as the new allowed packages may depend on other new packages that are not allowed to be updated.

Adding a non-official ebuild

Defining a new overlay

You can tell Portage to use ebuild files that are not included in the official Portage tree. Create a new directory (for example, /usr/local/portage) where third-party ebuild files will be located. Note that you must use a directory structure identical to the the official Portage tree.

Then define the PORTDIR_OVERLAY variable in /etc/portage/make.conf/custom, pointing to the previously created directory. Now, when using Portage, those ebuilds will be considered as part of the system and will not be deleted or overwritten at subsequent launches of emerge --sync.

Working with several overlay directories

Advanced developer users, who work in several overlay directories, test packages before they are added to the main tree or just prefer to use unofficial ebuilds from a variety of sources, will appreciate the layman tool provided by app-portage/layman. It will help keep your overlays up to date.

Configure layman, then add the overlays you want to use:

layman -a overlay_name

Imagine that you have two additional repositories named ~java~ (for your Java development project) and ~entapps~~ (for corporate applications for internal use). You can update those repositories by typing:

layman -S

Non-Portage maintained software

Using Portage with self-maintained software

Sometimes you may want to configure, install and maintain software individually without having Portage automate the process, even though Portage can provide the software titles. The most common cases are the kernel and nVidia drivers. It is possible to configure Portage so it knows that a certain package is manually installed on the system. This process is called _injectingi and is supported by Portage through the /etc/portage/profile/package.provided file.

For example, if you want to tell Portage that ~vanilla-sources- is installed manually, you need to add the following line to the 'package.provided' file: