Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc
It has been suggested that this article or section be merged into HOWTO Maintain Gentoo - "Best Practices". (Discuss)



There are a number of major elements that define any Linux distribution. One of the most important is the package management philosophy or system that the distribution embraces. For example, we can categorize distributions designed around RPM as Red Hat based, or we can say that Ubuntu or Knoppix are derived from Debian because they all use APT. The package manager found at the heart of Gentoo Linux is known as Portage.

Portage sets itself apart from nearly all other package managers in many ways. But the most significant difference is that it's not actually a package manager at all, but rather what's known as a meta-distribution engine. What this means is because of the power, flexibility, and configurability of Portage, very few Gentoo Linux installations are ever the same. Instead of being merely a tool used to install and remove software packages (although it performs these tasks with ease), the purpose of Portage is the construction of a complete Linux distribution unique to the user who created it. In this sense, Gentoo Linux is actually a meta-distribution. It's not a static product, but actually a robust toolkit for people wanting to build a custom operating system themselves.

The purpose of this HOWTO is to teach the "best-known practices" for working with Portage on a daily basis. This is not a primer or introduction to using Portage or emerge. If you're new to Gentoo, the best way to learn how to use these tools is by reading the Working with Gentoo chapter of the Gentoo Handbook. In this HOWTO we'll take an in-depth look at how Portage works and how we can make it work better.

Emerging Packages

The emerge command is the primary way one interacts with Portage. Nearly all actions that can be performed are available using any number of command-line options in combination. Here we will explain some of the more useful ones. For the full list, consult the emerge man page.
Display a message stating exactly what actions emerge will be performing and prompt the user to confirm them.
This is very similar to the --pretend option (-p), but it saves you from having to enter the command twice (once with and once without -p). --ask should be used almost every time you run emerge, so get into the habit of adding it now. ;)
root ~ # emerge -a patch

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

Calculating dependencies ...done!
[ebuild   R   ] sys-devel/patch-2.5.9-r1

Do you want me to merge these packages? [Yes/No]
Display the current USE flags available and selected for the given package, as well as size of the source and total size of data needed to be downloaded.
USE flags in (parens) are not available for your profile. +plus and -minus are enabled or disabled flags of course. asterisks* indicate that a flag has changed since the package was last emerged.
This option should also be enabled on every emerge, and is only useful with --ask or --pretend. Little known fact: this flag also controls the display of those "GNU info directory index" messages at the end of the emerge that no one cares about.
 root ~ # emerge -pv gimp

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

 Calculating dependencies ...done!
 [ebuild   R   ] media-gfx/gimp-2.2.7-r1  -aalib (-altivec) -debug -doc -gimpprint -gtkhtml
 -hardened  +jpeg -lcms +mmx +mng +png +python -scanner -smp +sse +svg -tiff* -wmf 13,647 kB

 Total size of downloads: 13,647 kB
Check the entire dependency tree of a package rather than just the immediate dependencies.
When the target is world, --deep checks the dependency trees of packages in the world file (more on this later). This option can find updates for packages that otherwise emerge would have not reported.
Display the dependency tree for the package/target.
This is an extremely useful option that is often overlooked. If you've ever tried to figure out what's pulling in a particular package, or just wanted to see what depends on what, this is the option for you. ;)
 root ~ # emerge -atv asterisk

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

 Calculating dependencies ...done!
 [ebuild  N    ] net-misc/asterisk-1.0.8  +alsa -bri -debug -doc +gtk -hardened +mmx -mysql
 -postgres -pri -resperl -speex -vmdbmysql -vmdbpostgres -zaptel 9,451 kB
 [ebuild  N    ]  dev-libs/newt-0.51.6  -gpm 152 kB
 [ebuild  N    ]   sys-libs/slang-1.4.9-r2  -cjk -unicode 616 kB
 [ebuild  N    ]  media-sound/sox-12.17.7-r1  +alsa -encode -mad +ogg 455 kB

 Total size of downloads: 10,675 kB

 Do you want me to merge these packages? [Yes/No]
Here we see asterisk depends on newt and sox, and newt depends on slang. Also, notice that the --tree option reverses the order that the packages are listed. The first package to be emerged appears at the bottom instead of the top.

Forcing Unstable Packages

The dreaded "masked by: missing keyword" message

This error message typically shows up when you try to emerge a package that has not been adequately tested on the platform you are using. The only way around the problem is to tell Portage to disregard all keywords by using ~* or *.

There are several ways to instruct portage to install 'unstable' packages (e.g., to use the ~x86 branch instead of x86). Many bad methods for installing unstable software have been spread. The following will explain how and how not to unmask unstable software.


One dubious approach is ACCEPT_KEYWORDS="~x86" emerge foo. This has several undesirable features:

If you like using unstable/testing software, you can place the ACCEPT_KEYWORDS="~x86" in your make.conf file.

Bad Method 2: emerge /path/to/ebuild

Another poor workaround is emerge /path/to/foo.ebuild. This has the annoying side effect of functioning as --oneshot. Portage will not add foo to your /var/lib/portage/world file. Unless foo happened to be in the world file beforehand, foo package will never be upgraded again unless you force it manually. emerge -u world will miss it.

A Good Method: /etc/portage/package.keywords

Details on this are given at TIP package.keywords. In short, to keyword an otherwise "unkeyworded" package you need to use either * or ~*. These are two special keywords.

* means "Match any stable keyword"
~* means "Match any unstable keyword"
** means "Match any keyword (even "")"

If the ebuild you are using is stable on x86, but not on sparc ( unkeyworded on sparc ) and you are on sparc, you would need to unmask it with *, since there are no ~arch keywords for ~* to match against.

For ** to work you need >=portage-2.1.2-r3.

If, for example, you wanted to explore currently uncharted territory by testing the Xen package on an AMD64 system, this is how you would do so:

File: /etc/portage/package.keywords
=app-emulation/xen-3.0.0_pre20051027        ~*
=sys-kernel/xen-sources-            ~*

Most of the time ~* works fine because there is an unstable keyword for one of the arches, however there are times when the package is stable on a number of arches, but not the arch that you are on. This is when using the * arch keyword comes in handy.

Maintaining Packages

Occasionally, portage may want to downgrade a package to an older version. Generally, there is a good reason behind it and it's best to downgrade it. There are exceptions though; for example linux-headers wanted to revert to 2.4.x when I have a 2.6.x kernel (Note: this is no longer the case with 2005.0 and later profiles). In /etc/portage/package.keywords we add a line or do

echo sys-kernel/linux-headers -* >> /etc/portage/package.keywords

Packages get downgraded when there is a huge security problem that isn't fixed in the newest versions and for other reasons, such as instablity being found that is very serious. Also, some devs just might accidentally mark something stable too early (they're only humans after all)

Packages sometimes try to creep back onto the system when they aren't needed. Early on, users of xorg-x11 may have noticed xfree trying to make its way back onto the system. To fix this, in /etc/portage/package.mask a line was added:

File: /etc/portage/package.mask

Packages are also hard-masked from time to time. One such example is realone. It's hard-masked due to the fact there is a security hole that could lead to a compromised system. If for some reason you want to use realone, there's a package.unmask file. Make a /etc/portage/package.unmask and enter this command:

echo media-video/realone >> /etc/portage/package.unmask

Also if you don't want a package to include a particular USE flag, there's a package.use. Make a /etc/portage/package.use and enter a function similar to this into a terminal

echo net-p2p/bittorrent -X >> /etc/portage/package.use

This would tell portage not to include X support when emerging bittorrent.

Tip: Use ACCEPT_KEYWORDS to find all dependencies

But when you just want to get newest version of GNOME, KDE or any other ebuild with a lot of dependencies it can be a real pain to keep doing "emerge -pv gnome" only to get one single dependency at the time. Therefore you can run:

ACCEPT_KEYWORDS="~x86" emerge -pv gnome

Get all the dependencies listed and add them to your /etc/portage/package.keywords .

Maintaining the World File

The world file is a record of packages which have been specifically installed by the user. More specifically it's a list of packages which the user wants to keep installed and updated on their system. It will not record the dependencies of those packages, but instead uses the dependencies of the currently installed packages to keep track of this information.

This means that, for example, if the emerge kde-meta command is issued, only kde-meta is added to the world file. The rest is worked out from its dependencies.

Contrary to some opinions, the world file is intended as a reference for the portage toolset only, and not to, for example, maintain a list of packages that the user wishes to be updated when running emerge -u world (this should be controlled using the package.* files under /etc/portage).

It is recommended that the world file is never edited directly, and instead the user uses the emerge command to maintain it. Below is a summary of the main commands. See emerge --help for information on all the available commands.

emerge -u system: Update the system (base packages) packages and their immediate dependencies. Also works for world.

emerge -uD system: Like above but also update all dependencies (i.e.: update dependencies of dependencies).

Why the difference between -u and -uD? Control. Using -u world instead of -uD world, the user can choose to maintain a known stable basic set of packages, only upgrading the top level of packages.

Tip: Use EMERGE_DEFAULT_OPTS in /etc/make.conf to set --deep as a default option. This way, all packages will get updated all the time. See /etc/make.conf.example for further help.

emerge --depclean --ask: List, ask the user to check and then remove all packages upon which no other package depends. In recent versions portage has gotten really good at not listing false positives here, but you should still check it just in case.

emerge --noreplace <package>: If a package is listed to be removed by depclean, but you don't want it removed, you can run this command and it will add the package to the world file, but won't actually install it.

emerge --oneshot <package>: Install a package, but don't add it to the world file. If want to re-emerge a package which you know you only want because it's a dependency of another package, use this command.

Troubleshooting: Lost World File

If you've lost your world file, portage no longer knows which packages you 'prefer' to be upgraded - this is generally not desirable. To (attempt to) fix your world file and add the packages type: regenworld

There's also a forum thread that provides information on how to fix your world file if regenworld doesn't work.

Understanding Portage's Formatted and Colored Output

Output from portage is compactly formatted to indicate a plethora of information.

Emerge "Pretend" Output

USE Flags

Color Output

Portage returns information to you using both symbols and colors. While the combination makes for a pretty output it also may appear confusing on first glance. Note that the color information is not required, so it repeats the symbolic output.


If you run the command

emerge --update --verbose --deep --newuse world

you might get something similar to

[ebuild   R    ] sys-kernel/linux-headers-2.6.11-r2  USE="-gcc64%" 36,470 kB 
[ebuild    U   ] sys-process/psmisc-22.2  USE="X* ipv6 nls (-selinux)" 238 kB

In this example the sys-kernel/linux-headers package would be reinstalled as indicated by the "R" at the beginning of the line. The sys-process/psmisc package is being updated, as shown by the "U" at the beginning of the line.


For those out there who want to simplify the whole "keywords" and "useflags" management, there is an application app-portage/flagedit which is insanely useful in managing the keys and useflags.

Per Package To enable a flag

flagedit foo-foo/foo +fooflag

To disable a flag ( regardless of what the make.conf file says and despite what your profile might want you to use )

flagedit foo-foo/foo -fooflag

To use whatever is specified by make.conf or your profile ( defaults )

flagedit foo-foo/foo %fooflag

Globally: aka make.conf as above, except without the foo-foo/foo part, ie:

flagedit +fooflag
flagedit -fooflag
flagedit %fooflag

if you wish to reset ALL the use flags for a particular package

flagedit foo-foo/foo %

Keywords to manipulate keywords, its the same as useflags, except you place a -- in the middle of the argument

flagedit foo-foo/foo -- +~fooArch
flagedit foo-foo/foo -- -~fooArch
flagedit -- -~fooArch
flagedit -- +~fooArch
flagedit foo-foo/foo -- %~fooArch

Package.* Folders

In Portage 2.2.0 package sets were introduced. In order for flagedit to work you have to apply the following patch to /usr/bin/flagedit

File: flagedit.0.0.7.patch
< our $VERSION='0.0.7';
< my $uf_file = '/etc/portage/package.use';
< my $kw_file = '/etc/portage/package.keywords';
< my $mc_file = '/etc/make.conf';
< my $portage_dir = '/usr/portage';
< my $alpha_order = 0;
< my $strict = 0;
> our $VERSION='';
> my $uf_file = (-d '/etc/portage/package.use' ? '/etc/portage/package.use/monolithic' : '/etc/portage/package.use');   #useflag file
> my $kw_file = (-d '/etc/portage/package.keywords' ? '/etc/portage/package.keywords/monolithic' : '/etc/portage/package.keywords');    #keyword file
> my $mc_file = '/etc/make.conf';                               #make.conf file in etc
> my $portage_dir = '/usr/portage';                     #directory where portage is installed
> my $alpha_order = 0;
> my $strict = 0;
sudo patch -p0 < flagedit.0.0.7.patch /usr/bin/flagedit


To update your entire system execute emerge --sync followed by emerge --update --ask --verbose --tree --deep --newuse world (or emerge -DavNut world) Since package dependencies constantly change, an emerge --depclean followed by a revdep-rebuild -- -p -v might be in order, but is certainly not required.

There have been a variety of "cruft scripts" and cleaners available, but they all seem to have fallen out of maintenance or just plain dropped off the face of the planet. If you have any good ones, please post them here.

Also See

GaMMa's Original Thread More verbose guide on portage

Porthole is a graphical interface to Portage. By default it is masked so I leave it to you to try it. Newbies should not use it to install or uninstall software, though when run with user privileges it makes for a convenient way to browse available software.

Retrieved from ""

Last modified: Fri, 26 Sep 2008 04:24:00 +0000 Hits: 112,592