Portage

Portage is the package manager used in Gentoo. Unlike most package managers, it is primarily used to handle source packages: Portage can automatically build source packages as you need them, while binary package managers primarily install pre-built tarballs.

The purpose of this article 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 are new to Gentoo, the best way to learn how to use these tools are by reading the Working with Gentoo chapter of the Gentoo Handbook. In this article we will 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, some of the more useful ones will be explained. For the full list, consult the emerge man page.


 * or
 * Display a message stating exactly what actions emerge will be performing and prompts you 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. ;)


 * or
 * Display the current USE flags available and selected for the given package, as well as the size of the source and total size of the data that needs to be downloaded.


 * USE flags in (parenthesis) are forced, masked or removed by your profile, -dash are disabled flags, asterisks* indicate that a flag has changed since the package was last emerged while percentage% indicate that it has been newly added or removed as an option.


 * This option should also be enabled on every emerge, and is only useful with --ask or --pretend.


 * or


 * Check the entire dependency tree for a package rather than just the immediate dependencies.


 * When the target is world, --deep checks the dependency trees of packages in the world file. This option can find updates for packages that emerge would not have reported otherwise.


 * or


 * Display the dependency tree for the specified packages.


 * If you have ever tried to figure out what is pulling in a particular package, or just wanted to see what depends on what, this is the option you should use.


 * Here you can see how 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 in. The first package to be emerged appears at the bottom instead of the top.


 * or
 * Resume an interrupted and unfinished emerge installation.


 * or
 * Search for a particular package. A quicker (but less informative) way to locate a package in the portage tree is


 * For example, to find nvidia drivers or utilities:
 * For example, to find nvidia drivers or utilities:

Another helpful tool for finding information about packages is, which is in the Gentoolkit package. Gentoolkit (and equery) can, of course, be installed with

Also see the Emerge Errors page for some troubleshooting tips.

You can search by regex using: emerge -s "%^python$"

Uncomment the package you do not want to upgrade in world at /var/lib/portage/world

Maintaining packages
There are four files other than that can be used for package maintenance:, ,  and.


 * Used to set per-package.
 * Content is a list of package atoms, one line each, followed by one or more arch names.
 * Except for the standard arch names that can be used with (as found in ),  also accepts three special "arch names":
 * Package is visible if it is stable on any architecture.
 * Package is visible if it is in testing on any architecture.
 * Package is always visible, are ignored completely.
 * For to work you need -2.1.2-r3 or higher.
 * Package is visible if it is in testing on any architecture.
 * Package is always visible, are ignored completely.
 * For to work you need -2.1.2-r3 or higher.
 * For to work you need -2.1.2-r3 or higher.

In addition to the "arch name" suffixes, the following version specifying prefixes can be used in conjunction with a version number suffix:


 * Package is visible if it has exactly the version number suffixed.
 * Package is visible if it is a later version than the version number suffixed.
 * Package is visible if it is later than or equal to the version number suffixed.
 * Package is visible if it is a later version than the version number suffixed.
 * Package is visible if it is later than or equal to the version number suffixed.
 * Package is visible if it is later than or equal to the version number suffixed.


 * Used to set per-package flags.
 * Content is a list of package atoms, one line each, followed by one or more flags.
 * Uses the same flags as, which can be found in  along with a description for each.
 * Uses the same flags as, which can be found in  along with a description for each.


 * and
 * Used to hide and unhide packages, respectively.
 * Content is a list of package atoms, one line each.

app-portage/flagedit
You can also use, which is useful in managing the keywords and USE flags.

Globally (make.conf)

To enable a flag

To disable a flag

To use whatever is specified by your profile.

Individual packages

To enable a flag

To disable a flag

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

If you wish to reset all the use flags for a particular package

Same thing for keywords, except you add two dashes (--) before the keyword

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

Maintaining the World File
Your world file contains every package you have explicitly installed. Dependencies for these files are not added, but checked for when needed instead.

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 commands that interact with your world file.


 * or
 * Upgrade the packages in your world file and their immediate dependencies.


 * or
 * Same as above, except all dependencies of every package is also upgraded.

Because of this difference you can, if you so choose, maintain a known stable set of packages, only upgrading the "top level" packages.


 * Lists all the packages that is not registered in your world file and is also not a dependency for another package. If you chose to continue the listed packages will be removed. This should be followed by a to rebuild any necessary dependencies removed by depclean. To keep a package from being removed, add the full package name (e.g. dev-java/sun-jdk:1.4) to its own line in.
 * Lists all the packages that is not registered in your world file and is also not a dependency for another package. If you chose to continue the listed packages will be removed. This should be followed by a to rebuild any necessary dependencies removed by depclean. To keep a package from being removed, add the full package name (e.g. dev-java/sun-jdk:1.4) to its own line in.


 * Adds an entry for the specified package in your world file. This can be used to "protect" packages from getting removed when running with --depclean.
 * Adds an entry for the specified package in your world file. This can be used to "protect" packages from getting removed when running with --depclean.


 * Install a package, but do not add it to the world file. If want to re-emerge a package which you only want because it is a dependency of another package, use this command.
 * Install a package, but do not add it to the world file. If want to re-emerge a package which you only want because it is a dependency of another package, use this command.

Output color and formatting
Output from Portage is compactly formatted to indicate a plethora of information.

State flags

 * B
 * blocked by an already installed package


 * b
 * blocked by an already installed package (conflict will be automatically resolved)


 * I
 * interactive package installation (required user input)


 * N
 * new, not currently installed


 * S
 * installs into a new slot


 * D
 * downgrading to older version


 * U
 * upgrade to newer version


 * R
 * re-emerging the same version, possibly due to new or removed use-flags


 * F
 * fetch restricted, must be manually downloaded


 * f
 * fetch, already downloaded


 * r
 * reinstall (forced for some reason, possibly due to slot or sub-slot)

USE flags

 * An unmarked USE flag is unchanged and enabled.
 * A dash (-) preceding a USE flag (yellow, green or blue) shows that it is disabled.
 * A percent symbol (%) following a USE flag indicates that it has been newly added or removed as an option for this package. Identical to yellow output.
 * An asterisk (*) following a USE flag indicates that its meaning/scope has been updated. Identical to green output.
 * Parentheses around a USE flag indicate that it is currently masked by your profile. This is usually because the USE flag can not be supported on the given platform (for example, the win32codecs on amd64 with non-binary packages) or is irrelevant; for example, sse is available on all amd64 CPUs, so there is no point being able to disable it in a 64-bit environment.

Color
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 and can be turned off, so it repeats the symbolic output.
 * red
 * The USE flag is enabled and has not changed.


 * yellow
 * The USE flag has been added, removed or masked since the package was last installed.


 * green
 * The USE flag has changed since the last time the package was installed, as the asterisk after it indicates.


 * blue
 * The USE flag is disabled, as the dash before it indicates.

Example
If you run the command

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.0 [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. The version being updated from is shown within box brackets and is colored blue.


 * The USE flag is yellow and followed by a percentage symbol (%), showing that that option has been added since the package was last installed. The dash (-) shows that it will be disabled during this update.
 * The USE flag is green and followed by an asterisk (*), because that USE flag has changed since the last time the package was installed. No "-" shows that it will be enabled during this update.
 * The and  USE flags is red since they are enabled and have not changed.
 * The USE flag is blue and preceded by a dash (-), because the flag is disabled. The parentheses  also show that it is an unavailable or irrelevant option.

Updating your system
To update your entire system execute

Since package dependencies constantly change you might also want to run the following.

"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.

Using 

There are several ways to instruct Portage to install 'unstable' packages, many of which are bad for several reasons. The proper way to do this by adding the package to your file

Details on this are given in the maintaining packages section of this article.

For packages that are available for your specific platform all you have to do is add the package to your file and add the architecture, prepended with a ~, on the same line separated by a space. For example, on an AMD 64 computer to install the unstable version of the kernel we would do

For packages that are only available for other platforms, you would have to use the other platforms architecture instead. For example, if we are not on x86 but would like to install quake3-demo anyway

Bad methods

Following are two examples that are most often not what you would want.

Bad Method 1: ACCEPT_KEYWORDS

One dubious approach is. This has several undesirable features:


 * It will merge unstable versions of all missing dependencies, not just the unstable version of foo.
 * It will be forgotten immediately. The next time you run, Portage will attempt to downgrade foo to the highest version that is stable. Portage will undo your changes, because you have told it to temporarily emerge an unstable version.
 * Messages about all other packages that might be incompatible are not displayed.

If you like using unstable/testing software, you can place the in your  file.

Bad Method 2: emerge /path/to/ebuild

Another poor workaround is. This has the annoying side effect of functioning as. Portage will not add foo to your file. Unless foo happened to be in the world file beforehand, the foo package will never be upgraded again unless you force it manually, will miss it.

How can I know program 'aa' is in which package that have installed??
Use equery in app-portage/gentoolkit

Use qfile in app-portage/portage-utils

How can I know program 'bb' is in which package that have not installed??
http://www.portagefilelist.de/

How can I know the files of package 'cc' ?

 * whereis cc (in sys-apps/util-linux)
 * equery f cc

How can I know what the USE mean ?

 * http://www.gentoo.org/dyn/use-index.xml
 * metadata eg: /usr/portage/app-i18n/ibus/metadata.xml
 * /usr/portage/profiles/use.desc
 * /usr/portage/profiles/use.local.desc

How can I know what packages I have installed by installed time? (Not Include Dependency)

 * genlop -l | grep -f /var/lib/portage/world

Useful commands
Per-Package Environment Variables