HOWTO use emerge and qpkg to install and manage packages on Gentoo
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
If a package includes or depends on other packages, they are installed automatically:
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:
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.
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] .
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):
Gentoolkit includes qpkg. To use it to list all installed packages:
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?
qpkg to query the database.
qpkg -f /bin/ls
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:
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: