Gentoo Wiki


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

Please improve it in any way that you see fit, and remove this notice {{Cleanup}} from the article. For tips on cleaning and formatting see Cleanup process



This article discusses how to deal with masked packages. For information on why packages are masked and the official methods of dealing with them, please see the Gentoo Handbook: Working With Portage: Mixing Software Branches.

Examples of Masked Packages

First, masked by keyword as a testing/unstable package: note the "(masked by: ~keyword)"

Code: Masked By ~keyword Package Example
 # emerge gnome-extra/gdesklets-core

  '''Calculating dependencies'''   
  !!! all ebuilds that could satisfy "gnome-extra/gdesklets-core" have been masked.
  !!! possible candidates are:
  - gnome-extra/gdesklets-core-0.26 (masked by: ~keyword)
  - gnome-extra/gdesklets-core-0.26.1 (masked by: ~keyword)
  !!! Error calculating dependencies. Please correct.

Second, a Hard masked package: note the: "(masked by: package.mask)"

Code: Hard Masked Package Example
# emerge -pv filewatcher

These are the packages that I would merge, in order:

Calculating dependencies   
!!! All ebuilds that could satisfy "filewatcher" have been masked.
!!! One of the following masked packages is required to complete your request:
- app-admin/filewatcher-2.4.0 (masked by: package.mask)
# Elfyn McBratney <> (28 Apr 2005)
# Masked for testing.

But you want to install the package anyway...

Masked by keyword

The new method is:

echo "gnome-extra/gdesklets-core" >> /etc/portage/package.keywords


echo "=gnome-extra/gdesklets-core-2.10.9" >> /etc/portage/package.keywords

if you want to unmask this specific version.

NOTE: You do not need to specify the architecture in package.keywords UNLESS you want to use an architecture which is different from your current one; this is not recommended.

If emerge says that the package was masked by "~* keyword", you'll need to take it literally and use, for instance:

echo "~gnome-extra/gdesklets-core-2.10.9 ~*" >> /etc/portage/package.keywords

Or if you using crossdev for build packages for multiple architectures.

echo "~gnome-extra/gdesklets-core-2.10.9 ~*" >> /etc/portage/package.keywords/cross-i686-pc-linux-gnu

OSB: i686-pc-linux-gnu in cross-i686-pc-linux-gnu name must change for each architecture.

Now, after performing either of the echoes above, emerge the file using the following:

emerge =gnome-extra/gdesklets-core-2.10.9

More info on this file provided here.


If you are on the command-line, app-portage/flagedit is a tool that automates adding entries to packages.keywords.

Sample usage:

flagedit gnome-extra/gdesklets-core -- +~x86

Kuroo is a useful KDE app which allows you to browse the portage tree and customise the install settings for any package.

It also enables you to install packages and any dependencies.

Even if you don't want kuroo to actually install packages, by queuing apps for install you can check dependencies, and also the whole installation, which allows you to unmask any dependencies that need it.

emerge -pv kuroo

It edits the standard portage files.

Invalid method (DO NOT USE)

ACCEPT_KEYWORDS="~x86" emerge gnome-extra/gdesklets-core

This is invalid and should not be used. Read this post on why ACCEPT_KEYWORDS isn't a good solution.... basically it's because emerge -u world will try to downgrade packages installed with ACCEPT_KEYWORDS, and can cause potentially fatal changes and cripple your system. The -U flag (upgrade only) is also deprecated for a very good reason - if package is broken, portage should downgrade it, -U disallows that behavior.

Masked by missing keyword

This is common if you are attempting to install the application when it has not been tested on your architecture.

If you have a CVS package marked has 9999 you can do the following: echo "media-gfx/retina **" >> /etc/portage/package.keywords

Bear in mind that if you install onto untested architecture for that application, it may not work.

Note: Note that usage of -* (as many people used to use it, atleast) has been obsoleted and it should no longer be used. It has been replaced by **. You may occaisionally come across third party overlays which still use -*. Please petition their maintainers to update them.

Hard Masked

Hard Masked packages are unmasked by adding them to /etc/portage/package.unmask. The syntax for this file, however, slightly differs from package.keywords:

echo "=app-admin/filewatcher-2.4.0" >> /etc/portage/package.unmask

This would unmask version 2.4.0 of app-admin/filewatcher. If you want to unmask every version of a package, just specify its name like so:

echo "app-admin/filewatcher" >> /etc/portage/package.unmask

Of course, it is also possible to use the < and > operators like in package.keywords.

Note, that a package which has been hard masked is usually marked as unstable as well. You probably have to add the package to both package.unmask and package.keywords.

Manually Hard Masking

Rarely, you will need to prevent the installation of a package. This might be the case, for example, when a bug in the ebuild script causes it to fail to compile on your system, thus preventing commands like emerge --update --deep world to function properly.

You can skip the ebuild of the offending package by adding its name to /etc/portage/package.mask like this:

echo "=sys-apps/file-4.17-r1" >> /etc/portage/package.mask

The syntax for this file is the same as package.unmask, described above.

Easy editing of /etc/portage/package.keywords


  1. Install: emerge flagedit
  2. Usage: flagedit <atom> -- +<keyword>, for example flagedit dev-util/libconf -- +~x86

User submitted scripts for unmasking packages


Here is a convenient script for emerging ~arch keyworded packages.

File: /usr/bin/gimme

############### gimme version 0.5.4 ################
# Script to add package names to package.keywords. #
# Originally by Tekmanx, re-written by Hackeron    #
# re-re-written by Gherald and edited by D. Watzke #

source /sbin/

 [[ $EUID != 0 ]]  && {
	eerror "You are not root!"
	exit 1

 [[ -z "$1" ]]  && {
	eerror "Please specify a package name (eg. gimme <package-name>)"
	exit 1

 [[ -d /etc/portage ]]  || mkdir -p /etc/portage

# Get fully-qualified ebuild name
FQN=$(ACCEPT_KEYWORDS="~x86" emerge -p $1 | grep "$1" | grep 'ebuild ' | tail -n2 | \
head -n1 | sed -e 's/\[ebuild.......\]\ //' -e 's/\[[[:digit:]].*\]//' -e 's/-[[:digit:]].*$//')

# We think there is either none or more than one package matching $1
# so we let the user deal with it
 [[ -z "$FQN" ]]  && emerge $@ -a; exit

if grep -q "^ *[\>\<=]*$FQN *" /etc/portage/package.keywords; then
	ewarn "/etc/portage/package.keywords already contains \"$EXISTING\""
	emerge $@ -a; exit
	einfo "Adding $FQN to package.keywords and emerging in 5 seconds."; sleep 5
	echo $FQN >> /etc/portage/package.keywords
	emerge $@ -a

Save this to a file named "gimme" in /usr/bin/ and do: chmod 755 /usr/bin/gimme Now you're ready to use the script. For example: gimme gdesklets-core

Script for /etc/portage/package.unmask

Here is a convenient script for unmasking packages that have been hard masked by /usr/portage/profiles/package.mask

File: /usr/local/bin/unmask
# This script will unmask any package masked by the actual profile.
# First we search for what is actually masked 
# in /usr/portage/profiles/package.mask then add a corresponding 
# line in /etc/portage/package.unmask
# Original by

source /sbin/

[ "$UID" -ne "0" ] && eerror "You must be root to run this script." && exit
[ -z "$1" ] && eerror "Please state a package name (eg. unmask kde-base/kode)" && exit
[ ! -d /etc/portage ] && einfo "Creating /etc/portage directory" && mkdir /etc/portage

if [ "$(grep "$1"-[0-9] /etc/portage/package.unmask 2>/dev/null)" ]; then
    ewarn "$1 already exists in package.unmask"
    PKG_LINE="$(grep "$1"-[0-9] /usr/portage/profiles/package.mask 2>/dev/null)"
    if [ ! $PKG_LINE ]; then
	PKG_LINE="$(grep "$1" /usr/portage/profiles/package.mask 2>/dev/null)"
    if [ ! $PKG_LINE ]; then
      ewarn "Could not find $1 in /usr/portage/profiles/package.mask" && exit 1
      ebegin "Adding $1 to package.unmask"
      echo $PKG_LINE >> /etc/portage/package.unmask
      eend $?

Again, put the file "unmask" in /usr/local/bin and do:

chmod 755 /usr/local/bin/unmask

Now you're ready to use the script... for instance:

unmask kde-base/kode # this version of unmask requires the full package name, including app-category/

You can also combine it with gimme, e.g.:

unmask kde-base/kode && gimme kode

Have fun. :)

Unmasking large groups of related packages

As of Portage 2.1, many of the /etc/portage/package.* files can now be directories instead. The files in the directory will be automatically concatenated by Portage. This is especially useful for modular X, which has almost 300 packages that need unmasking. Thus you can copy the modular X unmasking list to /etc/portage/package.keywords/xorg (and possibly /etc/portage/package.unmask/xorg) instead of /etc/portage/package.keywords, making the file FAR easier to manage.

Script for unmasking all dependencies

File: /bin/gimme-everything
# This script will unmask any package masked by specified keyword
# It is using flagedit to remove keyword
# Usage:  /bin/gimme-everything "=gnome-2.14.2" "+~amd64"
# Sorry that this is in one command line, but it was composed in one ;)
# author: mmazurek[at]

while true; do
   if emerge "$1" | grep '!!! All ebuilds'; then
      emerge "$1" | grep '!!! All ebuilds' | while read line; do
         n=$(echo $line | sed -e "s/.*\"\(.*\)\".*/\\1/");
         flagedit "$n" -- "$2";

Script for unmasking all dependencies (2)

This is another "unmask all dependencies" script, which does not need flagedit.

File: /sbin/unmask
#!/usr/bin/perl -w
use strict;

sub emerge {
        my $package = shift;
        $_ = `emerge -pv "${package}" 2>&1`;

        if(m/^- (\S+) \(masked by:.*package.mask/mi) {
                print "Unmasking ${1} in package.unmask\n";
                print UNMASK "=${1}\n";
                return 1;
        if(m/^- (\S+) \(masked by:.*\s+(\S+)\s+keyword/mi) {
                print "Unmasking ${1} in package.keywords\n";
                if ($2 eq "missing") {
                        print KEYWORDS "=${1} ** ~* *\n"
                } else {
                        print KEYWORDS "=${1} ${2}\n";
                return 1;
        if(m/^!!! masked or don't exist:\n(\S+)/mi) {
                while(emerge($1) != 0){}
                return 1;
        return 0;

open(UNMASK, ">>/etc/portage/package.unmask");
open(KEYWORDS, ">>/etc/portage/package.keywords");
our $package = $ARGV[0];
$package =~ s/"/\\"/g;
while(emerge($package) != 0){}
print "Done\n";


unmask ">media-video/mplayer-1.0_rc1"
Retrieved from ""

Last modified: Thu, 04 Sep 2008 05:36:00 +0000 Hits: 255,750