Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



This tutorial shows how to install ebuilds found on third-party sites or in the Gentoo Bugzilla that are currently not in the Portage tree.

As an example, x11-drivers/nvidia-drivers-100.14.11 will be installed.

General Concepts

All ebuilds have the following attributes:

It is very important to specify these attributes correctly.

Local Portage Overlay

The first thing to do is set up a local overlay directory. Add the following line to /etc/make.conf

File: /etc/make.conf

This directive will allow you to safely store your custom ebuilds, because emerge --sync removes any non-official files from the Portage tree (usually /usr/portage).

Note: If you also use layman, rather than adding PORTDIR_OVERLAY="/usr/local/portage" to your /etc/make.conf, just add /usr/local/portage to your /usr/local/portage/layman/make.conf

You can also install multiple overlays, e.g.:

File: /etc/make.conf
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-bmg-main"
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-bmg-gnome"
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-gentoo-de"
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-fluidportage"

Where each PORTDIR_OVERLAY entry points to the root of the rsync tree acquired by gensync (app-portage/gentoolkit-dev).

The reason for putting each entry on one line is to make it easy to comment-out any particular source of overlays. Alternatively, put all entries in one line, separating each entry with a space:

File: /etc/make.conf
PORTDIR_OVERLAY="/usr/local/portage-bmg-main /usr/local/portage-bmg-gnome"

See Local Portage Overlay for further information.

Finding the Ebuild

You can consult the articles TIP Overlays and Search_Bar_Plugin to get ebuilds from overlays. You can also get ebuild files directly from the gentoo bugzilla or just search the web for "<my program> ebuild".

Download the Ebuild

When placing the ebuild in /usr/local/portage, you must keep a similar structure to that of /usr/portage - category/program/program-version.ebuild

The category must match one of the lines in /usr/portage/profiles/categories

To download the ebuild, first look at the list of attachments and note that the second attachment file has a URL of

Create the initial directory structure for the ebuild, and download it:

# mkdir -p /usr/local/portage/x11-drivers/nvidia-drivers
# cd /usr/local/portage/x11-drivers/nvidia-drivers
# wget -O nvidia-drivers-100.14.11.ebuild

Unstable Packages

The new ebuild will likely be masked by keyword, so unmask it as is described in man portage, done by first opening /etc/portage/package.keywords in your favorite text editor.

If the directory (or the file) doesn't exist, you can safely create it:

# mkdir /etc/portage

Add the following line to /etc/portage/package.keywords, replacing <category> with the category the new ebuild is in (e.g. app-portage), and replacing <package> with the name of the package (e.g. gentoolkit).

File: /etc/portage/package.keywords

For nvidia-drivers:


Or, to mark only this specific version of the package as unstable: (note the equals sign at the start of the line)

File: /etc/portage/package.keywords

For nvidia-drivers:


Script Safety

An ebuild is a bash script run with root permissions, and can trash your system. A wise precaution, which will help to avoid overwriting existing files, is to have collision-protect enabled in /etc/make.conf, e.g.:

File: /etc/make.conf
FEATURES="collision-protect ccache parallel-fetch"

The sandbox, which provides a bit more protection, is enabled by default, which can be confirmed by:

# emerge --info | grep FEATURES

However, it is most important to read the ebuild, using your favourite text editor, to see what it does. If it tries to delete files in e.g. pkg_postinst, then there is no protection - the bash code will be executed with root permissions.

Once the script has been judged safe to execute on the PC with root permissions, digest it to fetch all the files specified in its SRC_URI.

# ebuild nvidia-drivers-100.14.11.ebuild digest

Files Subdirectory

Ebuilds often make use of their own ebuild-specific files, usually for patches to the source code. Such files are contained in its FILESDIR. To perform a quick check:

# grep FILESDIR *.ebuild

To copy the files from the Portage tree to the local overlay:

# cp -rf /usr/portage/x11-drivers/nvidia-drivers/files/* /usr/local/portage/x11-drivers/nvidia-drivers/files/

It is unlikely, but not impossible, that there are further subdirectories under files, hence the -r in the above command.

Other files which are intended to be placed in the files subdirectory might exist in the Attachments section of the bugzilla entry, so do not blindly assume that the ebuild author has made a mistake if the emerge fails (especially with an error message indicating a missing file) - look inside the ebuild at what it is doing, and what files it is using, and copy the needed files into the local ebuild's files subdirectory if that is where the ebuild is trying to find them. As with the ebuild file, look inside the files at their contents, using your favourite text editor, to check that they are not malicious.

After making any changes to the ebuild's directory tree, digest the ebuild again to update its Manifest file, which Portage checks to guard against unauthorized tampering with the ebuild's files.

# ebuild nvidia-drivers-100.14.11.ebuild digest

Note that if the ebuild uses a source URI other than the normal Gentoo mirror(s) specified in make.conf (the ebuild will contain a SRC_URI=<site> line) you will see the ebuild attempt (and fail) to download the source from all the Gentoo mirror(s) listed BEFORE attempting to get the source from the 3rd party URI listed in the ebuild. This is normal behaviour, simply allow the attempts to run, and eventually the correct site will be tried.

Install the Ebuild

To install the ebuild:

# emerge nvidia-drivers

To ensure that a specific version is emerged:

# emerge =nvidia-drivers-100.14.11

If the package name exists in more than one category, specify the category also:

# emerge x11-drivers/nvidia-drivers
# emerge =x11-drivers/nvidia-drivers-100.14.11

Temporary Space

If an emerge fails and the emerge is retried, Portage tries to be "helpful" by deciding whether to reuse its temporary storage area (which will default to /var/tmp/portage/x11-drivers/nvidia-drivers-100.14.11), which can potentially cause a perfectly good ebuild to fail, so clear it out before re-running emerge, with:

# rm -rf /var/tmp/portage/*

Do not run this command while emerging a package.

Useful Commands

To use the extremely useful commands shown below, first emerge the packages containing them:

# emerge -n genlop gentoolkit

List the versions available and installed:

# equery list -p -o -e nvidia-drivers

Show the files installed by a package:

# equery files nvidia-drivers

Show the history of emerges:

# genlop -l

See Also

From Gentoo-Wiki:

From Gentoo Forums:

# emerge =app-portage/portage-utils-0.1.28

From Gentoo Linux Documentation:


Retrieved from ""

Last modified: Sat, 11 Oct 2008 01:21:00 +0000 Hits: 159,710