Gentoo Portage Fundamentals

This reference is not meant to be complete or authoritative, it's a crash course. Only daily necessary skills with Portage will be discussed, the See Also section has links to more information. The reader is expected to know GNU/Linux at an administrative level.


The emerge utility of portage provides the methods to install, upgrade and remove packages. A second utility called equery provides information about installed and available pacakges. These are the only two utilities this document will cover, one must have the gentoolkit package installed for equery.

To maintain a Gentoo system one must

# Installing gentoolkit
root@myhost # emerge gentoolkit

Installing Packages

Before installing or searching update the portage tree if it hasn't been done in a while, meaning more than 24 hours. When the tree is up to date all searches and other queries will be against the latest set.

root@myhost # emerge --sync

Portage provides very simple tools to install packages and the dependent packages with little or no headache. Simply search to find the right package and then pretend to emerge the package to see what additional packages will be installed. Running this with the verbose flag will show the USE flags, very helpful.

# Find the package, search term can be a regexp, then install
root@myhost # emerge --search php
  [ truncated ]
root@myhost # emerge --pretend --verbose mod_php
  [ truncated ]
root@myhost # emerge mod_php
  [ truncated ]

Upgrading Packages or World

There are two types of upgrades, partial and full, or regular and deep. The partial or regular will only update packages that have a direct update. Using the deep option will update the package and it's dependencies.

# Regular: view update then do it update
root@myhost # emerge -puv world
root@myhost # emerge -uv world

# Deep: view update then do it update
root@myhost # emerge -puvD world
root@myhost # emerge -uvD world

If the system USE flags are changed then a check should be made to determine which packages need to be rebuilt.

root@myhost # emerge -puvDN world

Viewing Installed Packages

The utility equery provides information about the packages, use flags and other good stuffs. There are short options available, long options used for descriptive purposes. Say equery with no options to view short options and other commands.

root@myhost # equery which glibc
root@myhost # equery uses glibc
root@myhost # equery size glibc
root@myhost # equery depgraph glibc
root@myhost # equery depends glibc

Cleaning the System

Portage can remove packages too, it will also suggest a list of packages that aren't needed that may be removed at the administrators discretion.

# What might be albe to be removed?
root@myhost # emerge --clean --pretend --verbose world
root@myhost # emerge --depclean --pretend --verbose

# Pretend to remove cpio
root@myhost # emerge -pvC cpio
# Really remove
root@myhost # emerge -C cpio

This little BASH snippet will iterate over every package installed and use equery to determine it's dependencies.

for p in `equery --nocolor --quiet list`; do
	pkg=$(qatom $p|awk '{ print $1 "/"  $2 }')
	buf=`equery depends $pkg`
	if [ -n "$buf" ]; then
		echo "Dependencies for: $pkg";
		echo "  $buf";

See Also

Change Log