HOWTO use emerge and qpkg to install and manage packages on Gentoo

From LinuxReviews
Jump to navigationJump to search

emerge is the definitive command-line interface to the Portage system. It is primarily used for installing packages, and emerge can automatically handle any dependencies a desired package has. emerge manual page

It is based on Python and reads standard .ebuild files located in /usr/portage. The ebuild files describes how the source should be configured and installed, depending on variables set in /etc/make.conf.

Basic emerge commands



emerge packagename

If a package includes or depends on other packages, they are installed automatically:

emerge kde

would install all of KDE and all of KDEs depending packages.

To install a package and update all packages it depends on:

emerge -u package

To update a package, all packages it depends on and all packages they depend on (--deep, just about everything):

emerge -uD package


Uninstall a program package:

emerge -C package

If you like to type you can also use emerge unmerge package.

Searching for new software to install

Search for packages (package names only):

emerge -s keyword

Search for packages (using their description):

emerge -S keyword

To sync your local list for available packages with the latest portage tree:

emerge sync

Other usefull functions


Instead of actually installing a package, you can use --pretend to view what *would* have been installed if --pretend weren't used:

emerge -p package

Only fetch sourcefiles

Only download (--fetchonly) archive (and dependencies), don't build it:

emerge -f package

The downloaded packages are placed in /usr/portage/distfiles. It is safe to delete this folderes contents in order to save space.

If you want to download the source of all the files installed on a system:

emerge -efD world

Complete system update

You can at any point upgrade everything to the lastest available version. All it takes is (--update --deep):

emerge -uD world

Note that this will downgrade all packages installed with ACCEPT_KEYWORDS to the latest stable version. You should try emerge -uDp world before running -uD world.

USE flags

To view what USE flags are used to configure and install a package:

emerge -pv package

-p means pretend and tells emerge not to actually do anything, -v means verbose.

To install a package using other USE flags than those set in /etc/make.conf:

USE="-X -esd -gnome -gtk" emerge bitchx

USE="-X -gpm" emerge mc

Refer to the [use flag guide ../flagguide] .

Masked packages

Some packages are //masked// , meaning they won't install unless they are specifically demanded.

Why packages are masked

A package may be masked because it fails to compile or has serious bugs. It may also simply be masked because the latest version to brand new and therefore not tested enough to be included in the main portage tree.

Masked does not mean dangerous or unstable. Usually the latest stable release is what is used by default, while the development releases are masked.

A package can be masked for one, a few or all architectures (x86, ppc, sparc, sparc64, or alpha).

Installing masked packages

To install a masked package on sparc:

ACCEPT_KEYWORDS="~sparc" emerge package

To install a masked package on x86:

ACCEPT_KEYWORDS="~x86" emerge mozilla-firebird-cvs

It is quite possible to set ACCEPT_KEYWORDS="~x86" in /etc/make.conf. This is generally a bad idea, specially if you have no idea what you are doing.

To check for the latest masked version of a package:

ACCEPT_KEYWORDS="~x86" emerge -pv gimp


Some packages do not want to be installed even if you are using ACCEPT_KEYWORDS="~x86". These packages are randomly specified by the nice gentoo development theme and configured in:


If you are wondering if there is a later version of a package than what is available as a masked package in portage, try:

grep gimp /usr/portage/profiles/package.mask

If this shows you a line like..


.. then edit package.mask and add a # in front of that line, or:

` mv package.mask package.mask.tmp sed s/gimp/#gimp/g > package.mask `

Manageing installed packages

Gentoo lists the latest available and installed version of a package when you do a standard search:

emerge search package

But the 'emerge' tool can't make a list of all installed packages. To do so, Install Gentoolkit (not installed by default):

emerge gentoolkit

Gentoolkit includes qpkg. To use it to list all installed packages:

qpkg -I

Note that the package database is actually in /var/db/pkg/.

To view what's changed between the latest available version of a program and the latest installed version, use etcat -c.

etcat -c mozilla

What package installed program X?

Use qpkg to query the database.

qpkg -f /bin/ls

would output


Use which together with qpkg to insert the right path for executables:

qpkg -f which du

Read the qpkg manpage for more information.

You can get a list of all programs installed with emerge -evp --deep:

emerge -evp --deep world

Note that this lists wrong versions (=latest stable) for all packages installed with ACCEPT_KEYWORDS.

A better way of doing this is using qpkg, part of the package gentoolkit:

qpkg -I

How do I find duplicated / old versions installed?

You can use qpkg to find out if you got more than one version of the same program installed. qpkg is a part of gentoolkit.

qpkg --dups -v

Another way is to pretent to use the emerge command with the prune (P) flag:

emerge -Pvp