Readers should not try to follow instructions directly from the Handbook:Parts namespace (which is THIS page!). The sections displayed below are used as a skeleton for transcluding information into the computer architecture specific handbooks and are therefore lacking critical information.
Please visit the Handbook list to read instructions for a relevant computer architecture.
Using one branch
The ACCEPT_KEYWORDS variable defines the system's software branch. This variable is set in the /etc/portage/make.conf file and is configured to the stable branch by default. In this instance the default value is amd64.
# The following value is set by default, and does _not_ need explicitly defined. ACCEPT_KEYWORDS="amd64"
For a more casual experience, and less risk of instability or other issues, the Handbook recommends staying on the stable software branch. Since this is Portage's default behavior no changes are necessary. System administrators who want to live dangerously or receive the latest possible software updates should read the Testing section.
Hic sunt dracones! Running software from the testing branch may incur stability issues, imperfect package handling (for instance wrong/missing dependencies), frequent ebuild revisions (resulting in a lot of compiling) or packages that are broken in a other, often unexpected, manner. System administrators who are less comfortable with Gentoo or Linux in general should avoid the testing branch. As noted previously, the Handbook recommends staying with the stable, more thoroughly tested branch.
In cases where the system administrator would like to run a less-tested software stack, and in exchange receive 'bleeding edge' updates, the testing branch can be selected. To switch to the testing branch, set the ACCEPT_KEYWORDS value to ~amd64.
# Instructing Portage to use the testing branch (~) for the amd64 architecture. ACCEPT_KEYWORDS="~amd64"
Any architecture supported by the Gentoo project can move to a testing branch by simply adding a
~ (tilde symbol) in front of the architecture's ACCEPT_KEYWORDS value.
The testing branch is exactly what one would expect - unstable. If a package is in testing, it means that the developers believe it is functional but has not been thoroughly tested. Systems using the testing branch may be the first to encounter bugs in the package. If bugs are discovered, please file a bug report to make the developer(s) aware.
When changing from the stable to the testing branch and performing a @world update, it is normal for many - sometimes hundreds - of packages to be updated to the latest available versions. Updates generally correspond to the upstream project's current release. Keep in mind that, after moving from stable to testing, it may prove a challenge to revert back to the stable branch. This is to be expected.
Mixing stable with testing
It is possible to instruct Portage to allow the testing branch for particular packages, but use the stable branch for the rest of the system. To achieve this, add the package category and name into the /etc/portage/package.accept_keywords file. It is also possible to create a directory (with the same name) and list the package in a file under the directory.
For instance, to use the testing branch for gnumeric:
Testing particular versions
To use a specific software version from the testing branch but not allow updates from the testing branch for subsequent versions, a specific version of the package can be defined in the package.accept_keywords file. To define a specific version, the
= operator is utilized. It is also possible to enter a version range using the
In any case, if any package version information is defined, an operator must be used. Without version information, an operator cannot be used.
In the following Portage is instructed to allow the installation of a specific version of gnumeric, version 1.2.13, even if it is in the testing branch:
Gentoo developers mask packages for good reason, therefore unmasking a package is generally unsupportable by Gentoo's support channels. For this reason, it is to be expected for support requests related to package.unmask and/or package.mask to be ignored or marked as WONTFIX. Please exercise due caution when unmasking packages.
For the next example, presume a package has been masked by the Gentoo developers. When attempting to install the package, Portage will output a message indicating the package has been masked and will generally provide a reason for its masking. Next presume a system administrator, despite the reason mentioned in the package.mask file (situated in /var/db/repos/gentoo/profiles/ by default) still desires to install the package.
To do so, the system administrator would add the target package version (usually this will be the exact same line from the package.mask file in the profile) to the /etc/portage/package.unmask location.
For instance, if
=mail-client/mutt-2.2.9 is masked (poor doggy!), then it can be unmasked by adding the exact same line in the package.unmask location:
If an entry in /var/db/repos/gentoo/profiles/package.mask contains a range of package versions, then it is necessary to unmask only the version(s) that are actually needed. Please read the previous section to learn how to specify versions using operators.
It is also possible to instruct Portage to not install a certain package or not update to a specific version of a package. This is called masking a package. To mask a package, add qualifiers as necessary to the /etc/portage/package.mask location (either in that file or in a file in this directory).
For instance, to prevent Portage from installing kernel sources newer than gentoo-sources-4.9.16, add the following line at the package.mask location: