Gentoo Notes

Gentoo is the most recent distribution I’ve tried and I thoroughly recommend it. Gentoo have produced brilliant documentation - perhaps the best examples I’ve seen - so visit before reading anything here. This page is simply my short cut to the information I most regularly require.


First, some links to Gentoo documentation I’ve used:

Other links to useful resources:

System files

Tabulated below are a number of files and directories relevant to the Gentoo distribution. Many are common to most Linux distributions.

Location Description
/etc/env.d/ Holds environment configuration files, each of which contains environment variable assignments. These are processed by Gentoo (using env-update) in alpha-numeric order (0-9, a-z) to build the environment.
/etc/init.d/ Holds service initialisation scripts. These can be manually executed with /etc/init.d/[service] [start|stop|restart]. You can set which script starts at a runlevel with rc-update [add|del] [service] [runlevel]. The scripts are processed by Gentoo in alpha-numeric order (0-9, a-z).
/etc/runlevels/ Contains a subdirectory per runlevel, normally boot, default, nonetwork and single. Each directory contains soft links to init scripts held in /etc/init.d/, populated using the rc-update command (see the Set services to start at a given runlevel section).
/etc/conf.d/ Holds program configuration files.
/etc/conf.d/net Network config.
/etc/make.conf Define build variables, e.g. USE flags.
/etc/portage/package.keywords Place package names in here if you want to use the version from the testing branch rather than from the stable branch. You can place specific keywords at the end of a line, after the package name, e.g. app-office/gnumeric ~x86. See the Unstable and masked packages section.
/etc/portage/package.use Place package names in here if you want to change their use flags. You can place specific keywords at the end of a line, after the package name, e.g. dev-lang/python doc -berkdb to remove the berkdb use flag from python.
/usr/portage/profiles/package.mask Specifies which packages are masked and the reason why. Don’t edit this file.
/etc/portage/package.unmask Place package names here to unmask them (overriding /usr/portage/profiles/package.mask). It must contain exactly the same line as in /usr/portage/profiles/package.mask. Note that this file does not exist by default.
/etc/portage/package.mask Place package names here to mask them.
/usr/shared/doc/ From the 1. Ebuild HOWTO section in the Gentoo Developer Handbook: ‘Documentation files are installed in /usr/share/doc, into a subdirectory reflecting the name, version, and revision of the particular program. This applies to all programs: GNOME, KDE, X11 and console alike. However, some programs may install additional documentation and support files into a /usr/share hierarchy for their own purposes.’
/usr/portage/profiles/use.desc Holds a list of use flags and their descriptions. To check a particular use flag: cat /usr/portage/profiles/use.desc | grep [use flag]
/var/lib/portage/world A list of all packages installed by the user. Note that it does not list their dependencies. A system file, used by portage, so best not to screw it up.
/var/log/emerge.log Emerge log, showing packages that were installed/uninstalled.
/var/log/portage/elog/* Emerge logs, one for each package.
/var/log/portage/elog/summary.log Detailed messages about your last emerge.

Program files

Location Description
/etc/X11/xorg.conf X configuration, set by xorgconfig.
/etc/X11/xinit/xinitrc Default X initialisation config, which normally defines the start of a number of programs followed by a window manager.
/home/user/.xinitrc User-level X initialisation config. This is loaded by xinitrx, if found, in place of /etc/X11/xinitrc/xinitrc
/etc/X11/xdm/Xresources Read by the xsession file when you log in using xdm. Put X application config here (e.g. xterm config).

Installing and uninstalling packages


emerge -av whatever


emerge -Cav whatever

Note that this last command does not check dependencies, so use with care.

The a flag causes emerge to ask for confirmation and the v flag results in verbose output.

Constraints are unsatisfied

If you get something like the following:


  !!! Problem resolving dependencies for some/package from @selected


  The following REQUIRED_USE flag constraints are unsatisfied:
    cpu_flags_x86_foo? ( cpu_flags_x86_bar )


It means that you have cpu_flags_x86_foo enabled but not cpu_flags_x86_bar. Enable cpu_flags_x86_bar to resolve the USE flag constraints.


Emerge ffmpeg = ??? (Solved)

Package install / update logs

/var/log/emerge.log contains a list of packages installed/uninstalled.

/var/log/portage/elog/ contains logs, one for each package.

/var/log/portage/elog/summary.log has a summary of the emerge.

The elogviewer program can be used to view logs via a GUI, or elogv via Curses.

Find available packages

To search for packages whos description and name matches the [terms]:

emerge -Ss [terms]

It is case and space insensitive (e.g. if the term is ‘something’ it’ll match ‘SomeThing’ and ‘something’).

It will take a while if searching the description with the -S flag, so to search only the name:

emerge -s [terms]

Listing available masked packages

The equery tool can show masked packages, by listing those in the portage tree rather than those installed on your computer:

equery list -p [package]

See my equery notes for more on the equery command.

Updating environment

After doing an emerge it’s often important to update your environment. This consists of updating both the configuration files and the environment variables. To update the config files:

Configuration files


You’ll be presented with diffs of each configuration file that has changed, with a set of options for updating them. I use the following options most often:

Use the new configuration (the right hand side) in its entirety.
Use the original configration (the left hand side) in its entirety (“zap” i.e. kill/delete the new).
Merge the files, manually, but inspecting the changes side by side. When you are merging use l to choose the left (original) version and r to choose the right (updated) version.

I used to use etc-update, but dispatch-conf is quicker.


To update the environment variables:


Then start using the new environment:

source /etc/profile


dispatch-conf Manpage of dispatch-conf Manpage of env-update

Update portage tree

emerge --sync

Or if you can’t use rsync because of firewall restrictions:


Update everything / all installed packages

To update system packages:

emerge -avu system

And to update all packages:

emerge -avu world

Note that the packages’ dependencies are not updated, which isn’t necessary most of the time since any packages that are updated will install their dependencies anyway.

The -D switch will cause all dependencies to be updated too.

The -N switch rebuilds the packages with the USE flags you’ve specified in /etc/make.conf - do this if you’ve changed them since your last emerge.

List all installed packages

To list all installed packages, you can use qpkg or equery, provided with the gentoolkit ebuild.

qpkg -I


equery list

See my equery notes for more on the equery command.

Rebuild applications that depend on a particular library

Sometimes an application will segfault with mention of a particular library, e.g. (I had this when thunar was crashing). If a solution can’t be found on the web, rebuild the apps that depend on the library to see if that fixes the problem:

revdep-rebuild --library

Unstable and masked packages

If you attempt to emerge a package that’s unstable or masked, you’ll get a message informing you why the package can’t be installed (yet).

The following was lifted from Gentoo Linux Documentation – A Portage Introduction:

  • ~arch keyword means that the application is not tested sufficiently to be put in the stable branch. Wait a few days or weeks and try again.
  • -arch keyword or -* keyword means that the application does not work on your architecture. If you believe the package does work file a bug at our bugzilla]({:.weblink} website.
  • missing keyword means that the application has not been tested on your architecture yet. Ask the architecture porting team to test the package or test it for them and report your findings on our bugzilla website.
  • package.mask means that the package has been found corrupt, unstable or worse and has been deliberately marked as do-not-use.
  • profile means that the package has been found not suitable for your profile. The application might break your system if you installed it or is just not compatible with the profile you use.

There are 2 types of mask - hard and soft, otherwise known as unstable. Hard masked packages have been listed in /usr/portage/profiles/package.mask and can be unmasked by editing /etc/portage/package.unmask. Soft masked (unstable) packages can be unmasked by editing /etc/portage/package.keywords.

Soft Masks (aka Unstable)

You can unmask a soft masked package by adding the package name to /etc/portage/package.keywords and optionally specifying the architecture. Useful operators include =, <=, <, >, >=, though you don’t have to use them.

[comparison operator][category]/[name] ~arch

For example:

app-office/mozilla-sunbird-bin ~x86
=www-apache/mod_jk-1.2.13 ~x86

Hard Masks

You can unmask a hard masked package by adding the package name to /etc/portage/package.unmask. Useful operators include =, <=, <, >, >=, one of which you have to use. Note that hard masked packages are not supported by Gentoo, so you won’t get any support from them if you hit problems.

[comparison operator][category]/[name]

For example:


Forcing specific version of a package

When the package version is (soft) masked, add it to /etc/portage/package.keywords:


When the package version is not masked, the above setting in package.keywords will not work. Instead mask particular versions in /etc/portage/package.mask to force the version you want:


Set services to start at a given runlevel


rc-update add [service] [runlevel]


rc-update del [service] [runlevel]

The [service] must be in /etc/init.d/ and the [runlevel] must be in /etc/runlevels/.

Update profile

Follow the Gentoo Upgrading Guide, because it can be more complicated than the two commands listed below. You will need the eselect program installed.

To list all available profiles:

eselect profile list

To switch to profile [n]:

eselect profile set [n]

Clear disk space

See Clear disk space on Gentoo.

Last modified: 27/03/2016 Tags: (none)

This website is a personal resource. Nothing here is guaranteed correct or complete, so use at your own risk and try not to delete the Internet. -Stephan

Site Info

Privacy policy

Go to top