emerge: The Third Way

This is a very brief overview of package management under Gentoo. I'm happy for readers to mail me if they have questions, and I will update this section in response to any questions.

Gentoo differs from many other distributions by compiling applications from source when they are installed rather than using a precompiled binary. The advantage of this is that applications are optimised for your preferences, and it is very easy to mix stable and unstable packages on the same system; the disadvantage is that installing applications, particularly large ones such as X or KDE, can take a significant time.

Finding a package

All Gentoo packages are listed at http://www.gentoo.org/dyn/pkgs/index.xml; however, the '''emerge''' command can be used to search for a package. To find a package which includes "gimp" in its name:

emerge -s gimp

Changing the '''-s''' to '''-S''' will result in the package descriptions as well as the names to be searched; however, this is significantly slower.

Installing a package

The '''emerge''' command is used to install packages. By default any dependencies not already present are also installed, so it can be helpful to first do a "pretend" emerge, which will simply list all packages to be installed:

emerge gimp -p

Removing a package

Note that when a package is removed dependencies are not checked, so it is possible to cause serious problems by emerging a basic package. In particular removing Python will cause hours of fun trying to replace it as the emerge command is itself written in Python. To remove a package:

emerge gimp -C

Updating packages

Before updating any packages the portage tree needs to be synchronised. This does not download new packages itself and takes typically thirty seconds to run over a broadband link:

emerge --sync

Individual packages may be updated by simply re-emerging them:

emerge gimp

To get a list of all core system packages for which an update is available:

emerge -up system

...where "-up" means "update" and "pretend" (ie, don't actually install). To get a list of all packages, both system and applications, that need updating:

emerge -up world

To actually carry out the update use either of the previous two commands without the "p" flag, for example:

emerge -u world

Keeping your system completely up-to-date

Before you update any packages, you need to make sure that your portage tree is up-to-date. The following command will synchronise your tree with the latest on the Gentoo servers:

emerge --sync

To completely update all the packages in your world file, all their dependencies, and remerge all packages so that they match your current USE flag settings, use the following command:

emerge -auDNv world

The 'a' flag makes portage list all the packages that would be merged, as with 'p', but then asks you whether you would like to merge them, meaning portage does not have to calculate the dependencies twice. The 'u' flag causes all packages in the world file (/var/lib/portage/world) to be updated, and the 'D' flag the same for their dependencies. The 'N' remerges all packages whose USE flags settings have been changed since the last merge, either in /etc/make.conf or /etc/portage/package.use. You can optionally use the 'v' flag, which will give verbose output of the list of packages to be merged (use flag settings will be shown, '+' indicating a flag that will be used, '-' one that will not be used, and '*' indicating any flags whose state has changed since the last merge.

This will likely take a long time, so you may well want to leave this running overnight or while you go to work rather than doing this while you need to be using your PC.

Once you have used this command, you can safely run the following command, which will check all the dependencies of currently merged packages and remove packages that have been made redundant (i.e., those that are no longer needed due to other packages having been unmerged):

emerge -a depclean

Under no circumstances should you do this unless you have done an "emerge -uDN world"; it can seriously bork you system!

This will give you a list of packages that will be unmerged and then ask you whether you wish to proceed with the operation. NOTE, check all the packages in the list; if there are any that you do not want unmerged, you should cancel the operation and add these packages the 'world' file (/var/lib/portage/world), using any text editor (as root). Then repeat the operation and let portage do its thing.

Again, this may take a while, although not nearly as long as the previous command. However, once you have done a depclean, you need to use the following command, which may take a lot longer, as many packages could need to be rebuilt:

revdep-rebuild -a

Note: before you can use revdep-rebuild, you need to merge the gentoolkit, which contains the program:

emerge gentoolkit

This program is a reverse-dependency rebuilder; "It will scan your installed ebuilds to find packages that have become broken as a result of an upgrade of a package they depend on. It can emerge those packages for you but it can also happen that a given package does not work anymore with the currently installed dependencies, in which case you should upgrade the broken package to a more recent version." revdep-revuild passes options to emerge, so you can use the 'a' flag.

Your system is now completely up-to-date.

Downloading packages

Sometime it is desirable to download all the packages required without actually installing them. For example, you may run a "sync" every night, then download any updated packages automatically. They can be manually installed later. To download all updated packages:

emerge -f world

Emerge help

Emerge has both a manpage and built-in help '''emerge -h'''.

Other Gentoo utilities

It is worth installing the gentoolkit '''emerge gentoolkit''' as it contains a number of useful utilities including '''equery''', which allows packages to be searched, listed, etc.

Some Tips

For large packages, compilations can take a long time and seriously affect the performance of your PC if you're trying to use it at the same time. In order to fix this, add the following line to your /etc/make.conf:


This causes packages to be compiled with low priority. It won't have any affect if the PC isn't doing anything else, but if you are trying to use it, then the compile process will run slower and not affect how the PC responds to what you're trying to do. It's perfectly possible to play CPU intensive 3D games whilst emerge runs in the background with this option set.

Gentoo forums

Probably the best Gentoo support on the net is at the Gentoo forums: a search there is strongly recommended if you have problems with Gentoo.

ManagingPackages/Emerge (last edited 2009-01-25 08:19:16 by 86)