Gentoo Wiki


This article is part of the Tips & Tricks series.
Terminals / Shells Network X Window System Portage System Filesystems Kernel Other


Creation of package.keywords

To create package.keywords, do the following:

# mkdir /etc/portage
# cd /etc/portage
# touch package.keywords

Structure of package.keywords

The package.keywords file serves as a way to get portage to emerge normally hidden packages. Each line consists of a package-keyword pair. For example,

net-wireless/ndiswrapper ~x86

where, net-wireless/ndiswrapper is the package, and ~x86 is the keyword.

See Keywords article or How to use portage correctly Gentoo Forum thread for more information.

Package Modifiers

Since packages come in different versions and revisions, the following table describes how to specifically select for a subset of versions or revisions:

Symbol Action Example Effect
= Select a specific version =x11-base/opengl-update-1.7 ~x86 This will unmask only version 1.7
* Select versions using a wildcard =dev-ruby/rails-1.1* ~x86 This will unmask versions 1.1.0, 1.1.1 etc. Note, this will not work if you put a period before the wildcard
>= Select version greater than or equal to >=x11-base/opengl-update-1.7 ~x86 This will unmask all versions greater than or equal to 1.7
<= Select version less than or equal to <=x11-base/opengl-update-1.7 ~x86 This will unmask all versions less than or equal to 1.7
~ Select a specific version and any revisions to that version ~net-www/mozilla-firefox-0.9.1 ~x86 this will unmask firefox-0.9.1 as well as any future revisions such as -0.9.1-r1, -0.9.1-r2, etc. It will not unmask -0.9.2 or any other version.

Keyword Modifiers

Keywords can take on one of three forms:

Symbol Action
arch unmask the package for the given arch (e.g. x86, powerPC, etc.)
* unmask the package when it becomes stable on any architecture
~* unmask the package when it is unstable on any architecture

You would typically use the last two without a version specifier, such as in arch testing.

Note: The package sys-kernel/linux-headers requires -* instead of ~x86 when using keyword modifiers.
=sys-kernel/linux-headers-2.6.5 -*

Editing package.keywords

This file is nothing more than a simple text document. Therefore, you can simply use your favorite text editor (e.g. nano, emacs, vi) to edit this file. If you get tired editing package.keywords (and package.use) by hand, you can use app-portage/flagedit instead. See HOWTO_Use_Portage_Correctly#TimeSavers

Miscellaneous Tips

Alternative organization of package.keywords

The Tip below is kind of outdated. If your system grows you might want to consider putting all the keyworded packages in one file.

Example: you want foo/foo to be keyworded but the dependency requires that foo/foobar and foo/barbar have to be keyworded too. Then you could either do as the Tip below suggested it or do the following.

# mkdir -p /etc/portage/package.keywords                                    # yes we create a directory not a file!!!
# echo "foo/foo" > /etc/portage/package.keywords/foo                        # the name for the file can be chosen freely
# echo -e "foo/foobar \nfoo/barbar" >> /etc/portage/package.keywords/foo

You could also use it for package.use, package.unmask and so on.

You do not have to use the ~arch anymore unless you want to install a ~x86 package on an ~amd64 machine.

Easy cleaning of package.keywords

See Easy cleaning of package.keywords page.

Generate package.keywords from installed packages

The following command-sequence generates new /etc/portage/package.{keywords/unmask) files based upon the packages currently installed. You will need to have emerged app-portage/gentoolkit before using this script.



echo "Rewriting package.keywords"
equery -N l -i | sed -nre '/(M~|M | ~)/ s/(^.+\] | \(.+$)//gp' | sed -re 's/^/=/g' >> ${KEYWORDS}

echo "Rewriting package.unmask"
ALL=$(wc -l ${KEYWORDS} | awk '{print $1}')
while read KEYWORD; do
	COUNT=$[$COUNT + 1]
	echo -ne " $[${COUNT} * 100 / ${ALL}]% finished\r"
	emerge -pv ${KEYWORD} | grep "package.mask" &>/dev/null && echo ${KEYWORD} >> ${UNMASK}
done < ${KEYWORDS}
echo "                                               "
echo "Done"

You may use this to:

The latter is useful, if you unmasked a lot of packages and you find the regular dependency problems occurring on portage-tree-updates annoying.

After execution, check whether emerge -pve world exits without errors. If not, you may either correct errors by hand or just restore the backup.

Alternative Script

If you have accidentally deleted or severely altered your /etc/portage/package.keywords file, either by incorrectly appending keywords from the shell or accidental deletion, you can use the following script to help regenerate and sort it:

File: /usr/sbin/keywords-file-regen

function help {

  echo "Syntax: keyword-file-regen [options]"
  echo "   --update-reg		Update your keywords file"
  echo "   --update-local	Update your portage overlay"
  echo "   --update-masked	Update masked packages"
  echo "   --update-all		Update all of the keywords file"

function start {
	if [ -f $k ]
	    rm $k
function update_reg {
	emerge -puON world | 
	grep UD | 
	sed -e "s/\[ebuild  *UD\] //g" -e "s/-[0-9].*//" >> $k
function update_local {
	emerge -puON world | 
	grep "[1]" | 
	sed -e "s/\[ebuild  *UD\] //g" -e "s/-[0-9].*//" | 
	grep -v "ebuild" | 
	sed 's/ /\n/g' >> $k
function update_masked {
	b=`emerge -pv world | grep -n exist | sed "s/:.*//"`
	b=$(expr $b + 1)
	emerge -pv world | sed -e "${b}!d" -e 's/ /\n/g' >> $k
	while echo `emerge -pD world` | grep "masked"; do
		emerge -pD world |
		sed -e '/\!\!\!/!d' |
		sed -n '1p' |
		sed -e 's/" .*$//' -e 's/!.*"//' -e "s/-[0-9].*//" -e 's/[=,~,<,>]//' -e 's/[=]//' >> $k
function sort_file {
	sort $k -o $k

if [ ! "$1" ];

while [ "$1" ]; do

  case "$1" in






Errors related to package.keywords

Invalid atom in /etc/portage/package.keywords

This error may occur, if a version number has been added to a package name but none of the package modifiers have been used. For example,

net-misc/utelnetd-0.1.9  # This is not correct

An easy way to solve this problem is to modify the line by (1) removing the version number information, or (2) use an appropriate package modifier.

Retrieved from ""

Last modified: Sat, 23 Aug 2008 08:58:00 +0000 Hits: 51,603