Probably you are not alone and not the fist that run in to the problem so see: and

Program crashes or does not start

On gui applications start them from the console, where errors and warnings appear. Check also logfiles and dmesg.

oowriter to start openoffice

Try also to run them as root to see if there a problem with the permissions.

When crashed type in the console Ctrl + C to quit it.

Boot errors

It is wise to have the text running by during boot, so it can be observed what is going on and be even interacted. Something could go wrong with X and when you need to login to the graphical login manager, you might be stuck with a non working keyboard or mouse.

After the boot loader has loaded the kernel, the gentoo init scripts are started. When this happens you can press the button I to go into an interactive boot mode.

First some none interruptible tasks are performed, but then the menu comes and shows step by step what service has to be started. For more serious error you can jump directly into the text console and try to fix this way your installation. The command rc-status shows what init scripts are running.

Emerge update failures

To do the rest and look later for the problem.

emerge --resume --skipfirst


emerge --resume


emerge --skipfirst

Optimists believe that this could fix the problem, since it changes the sequence of the list to be emerged.

Check also that the system time is correct since many builds are based on that.


When retrying the package that failed and you try re-emerge it, make sure you type emerge --oneshot<ebuild> or emerge -1<ebuild> (1 as one, not as l) when the ebuild has been selected due to dependencies, so it will not be put in the world file and might be deleted once nothing depends anymore on the package. The world file should not be a collection of bad ebuilds. It should be small and clean.

Try to find out more and where the ebuild fails, see: Install an ebuild using the command ebuild

Poker solutions

MAKEOPTS="-j1" emerge -1 sys-apps/coreutils some ebuilds do just emerge with MAKEOPTS -j1

Open the console and type su - this creates a basic environment with much less environmental variables.

The wimpy solution

Finding out why and resolving is one method, where the discussion forum is a valuable source of information. The other method is waiting for better times and mask the one causing the problem or unmask a newer not yet stable version.

If you have time emerging everything removes lots of dependency errors:

emerge -uDNav --with-bdeps y --backtrack 100 @world or emerge -e <problematic ebuild>

Problems with use flags

Do USE="-<problematic useflag>" emerge -1<my problem ebuild>

to see if emerge works with disabling (or enabling) the useflag. Avoid doing it globally in /etc/portage/make.conf do it for a specific package in /etc/portage/package.use as:

=<my-problem-category></my problem ebuild><-its version> -doc

Adding the version is recommended, since it can be assumed that the ebuild will emerge in the future.

Critical useflags are:

  1. doc creates the documentation requiring tools that do not emerge (read the documentation online instead)

  2. bindist makes that binary version get installed there where it is possible (and could therefore bring lots of dependency conflicts)

Slot issues

Slots allow that a package can be installed multiple times. This is common for some packages as python (version 2 and 3) and kernel sources. However there are many packages or versions that can not be installed at the same time. This can cause a dependency conflict and therefore the system refuses to be updated. Possible solutions are:

Useflags that are not enabled by the new version but got enabled by the old version and package wants also to have the useflag enabled for the updated package. It refuses to accept the new package due to the missing useflag. The solution is to also enable the useflag for the updated package.

Circular blockers

This is like what was first the egg or the chicken? One ebuild can not be installed because an other one is missing, however the missing ebuild can also not be installed since the same first ebuild is missing. A way out is playing with the USE flags and call as: USE="-doc" emerge<one of the ebuild>

Missing libraries

When updates fails, the reason is reported, however in a form requiring detailed know how. If a library is missing, then it is probably really not there. Check this as ls /usr/lib | grep '' and do not provide a version number, so all versions are reported.

If the version is not there but others, it is an update bug. You can try to fix it making a symbolic link of the missing library to the so version that has no version. Then try updating your system and emerge @preserved-rebuild (or the old way revdep-rebuild). When everything done remove your manually added symlinks.

Checksum error or digest verification failure

If emerge fails due to an MD5 checksum error (or digest verification failure) you can manually delete the file in /usr/portage/distfiles or/and /usr/portage/packets or/and /usr/portage/packets/<ebuild> and redo emerge from the same mirror or modify the mirror list in /etc/make.conf to try it from an other mirror and redo a emerge --sync again. Inside portage each ebuild has it own manifest file containing all checksums of all files used during emerge, alternatively you could update yourself the manifest file. However this is a dirty hack that gets wiped out next time you emerge --sync your portage and the reason remains why manifest did not match, however it might solve your problem:

ebuild /usr/portage/media-video/realplayer/realplayer- digest

Emerge blockages

Instead emerge ---update -- deep world directly try first emerge --update --deep system

One ebuild can not be updated because an other ebuild blocks the update. Check if the other one who blocks is part of the system profile emerge -pv --unmerge <package that blocks> if not unmerge it.

Check also if /var/lib/portage/world is clean. Clean means that just files are there that you know and that you manually and intentionally have emerged.

Blockage due to licenses

If you get something as

!!! All ebuilds that could satisfy "app-emulation/virtualbox-bin" have been masked. !!! One of the following masked packages is required to complete your request: - app-emulation/virtualbox-bin-3.1.2 (masked by: PUEL license(s)) A copy of the "PUEL" license is located at "/usr/portage/licenses/PUEL".

Then it is due to the lawyers out there. Especially sun Microsystems and now Oracle that owns them tries to give you a hard time. Maybe worth to use an other java implementation as Alternatives are switching to dev-java/icedtea-bin:6 or the source-based dev-java/icedtea:6? You need to accept the license by putting something as


into /etc/portage/make.conf.

Or add it to the license file /etc/portage/package.license

        >=dev-java/sun-jdk- Oracle-BCLA-JavaSE

Example 14.3. License blockage example

!!! The following updates are masked by LICENSE changes: - www-plugins/adobe-flash- (masked by: AdobeFlash-11.x license(s)) A copy of the 'AdobeFlash-11.x' license is located at '/usr/portage/licenses/AdobeFlash-11.x'. For more information, see the MASKED PACKAGES section in the emerge man page or refer to the Gentoo Handbook.

Does not give a useful hint what to do. To solve it add the following:

        >=www-plugins/adobe-flash- AdobeFlash-11.x



Access violation

Emerge does the installation in two steps. The installation goes into a temporary directory and then the merge follows to put it into the real root system. If install tries to write directly into the real root system, then the sandbox gives access violation with permission denied.

This feature can be turned off by calling FEATURES="-sandbox" emerge v4l-dvb-hg . This should just be considered when no other solution can be found.

It is possible but not recommended at all to have this permanently active and put the line


in /etc/portage/make.conf.

Perl emerge failures

perl goes in /usr/lib/perl5 where the installed versions can be seen. Additional there is the emerge perl-info. Special updating perl procedures might remove lots of perl emerge problems. Commands for that are perl-clenar --all perl-cleaner --reallyall or emerge gentoo-perl-helpers that creates ebuild sets to clean and update a perl version.

Packages do not emerge on small machines

The reason can be that the system runs out of memory. Adding additional swap space, either as a swap partition or a swap file might be the solution.


A swapfile or partition might be required when huge packages are getting complied. The swap could be on an external USB Harddisk. swapon /dev/sd<?>.

Running out of RAM

If it is a multicore CPU /etc/portage/make.conf can be modified to have


to not use all cores in parallel. Compilation takes longer but uses less RAM.

Small embedded devices

When having installed Gentoo to an SDcard,USB stick, USB HD or SATA drive, you might consider to plug it into a more power full PC and chroot the system and then do the emerge.

Sample code to chroot using a swap file on hda3:


mkdir /mnt/gentoo/

mount /dev/usbstk2 /mnt/gentoo

mount /dev/usbstk1 /mnt/gentoo/boot

mount /dev/hda3 /mnt/gentoo/swap

cp -L /etc/resolv.conf /mnt/gentoo/etc/

mount -t proc none /mnt/gentoo/proc

mount -o bind /dev /mnt/gentoo/dev

chroot /mnt/gentoo /bin/bash


source /etc/profile

export PS1="(chroot) $PS1"

swapon /swap/swapfile

swapon -s

Emerge wants to emerge stuff that you don't want

After removing some programs it can happen that when you do emerge --update --deep world --pretend, you see that emerge wants to emerge stuff that you don't want. The reason is that there are still some packages or libraries installed that want these updates.

Dependencies go in two directions.

In the down direction a package required to have other packages so it emerges. To find those ebuilds take one of the unwanted ebuilds that emerge --update --deep world --pretend lists and do a equery depends =kdelibs-3.5.10-r6. As result a list of ebuilds appear that still desire kdelibs-3.5.10-r6. Using a gui portage tool (as porthole) you can check if those ebuilds are installed and when so un-merge them using the appropriate version.

If the up direction the package is required by an other package installed and this packages can be found using emerge with the -t option

Also things as USE="-systemd" emerge --update --deep world --pretend can help

Check also files in /etc/portage as /etc/portage/package.use

Emerging groups of ebuilds

When having troubles with big ebuilds also dependent ebuilds need to be re-emerged. The following sample shows how to do this for the drivers related to xorg-server emerge -1tav $(qlist -IC x11-drivers)

No keyboard and mouse in X after update

A first check is to go into the BIOS and see if the keyboard and mouse work. If this is the case than it is a X issue. Boot with a live CD (or use an other computer and access the keyboard-less one with ssh) and disable bootmanager in /etc/conf.d/xdm then reboot and try to fix it using the console. emerge -1tav $(qlist -IC x11-drivers) might be a good option for that or ls /var/db/pkg/x11-drivers to see what x11-drivers you got. Alternatively plug in usb mouse/keyboard.

Problems with after a gcc update

On major gcc updates incompatibilities might occur. See gcc chapter. Or Gentoo gcc update guide specially made for this topic. One way out is: Wait until you can leave your computer busy for some days and do the last hope procedure

emerge -e system followed by emerge -e world

Python version conflicts

Check that python packages (as: pycairo, pygtk, ... ) get install using the right python version /usr/lib/python<n.m>/site-packages/. If not start python-updater, and if this not helps install old version python is a slotted package, so multiple versions can exist on your PC. Then switch back and forward using eselect python list and eselect python set<n>. Decide on the python version that you like to used and unmerge and delete everything else.

No Internet connection after update

Check if you have the DHCP client running. If not emerge the DHCP client, however without Ethernet connection it is impossible. Way out. /etc/cinfig.d/net set to fix IP address. Then emerge dhcp client and re-edit /etc/config.d/net to have DHCP.

Dependency troubles

Example how to build dependencies that depend on a lib

revdep-rebuild --soname

/var/lib/portage/world is a file containing a list of all packages emerged. A clean Gentoo installation must have a clean world file! See the wold file section for more details

Try emerge -ea<package> that installs the package with all necessary packages in the tree.

A library is required but the library is obsolete or missing, so compile everything that has dependencies to that library with the hope that the dependencies will be removed: revdep-rebuild --library '<path to and library>'

If revdep-rebuild exits due to an error and gets restarted afterwards, the checking phase is skipped and everything will be re-emerged. To reset this call it as revdep-rebuil -i. This ignores the temporary files. Alternatively you could do rm /var/cache/revdep-rebuild/*.rr

Using Portage tools


Missing files or don't know who installed (emerge gentoolkit first)

equery belongs /usr/bin/<filename>

equery belongs<filename-for-files-in-the-path>

equery depends<packet-name>

equery depgraph<packet-name>

Example: equery depgraph =clanlib-0.6.5-r4

equery files <packetname> lists files belonging to an ebuild

equery hasuse<useflag-name> files having used this use flag

equery uses <packetname> what use flags have been used.

Is as emerge -pv<packagename> but more verbose.


emerge portage-utils (faster because in c written but more limited than gentoolkit)

How to find a package to which a file belongs


or if you do not know where it is

qfile $(which<command>)

Listing packages which depend on some package

qdepends -a <packetname>

Listing files that belong to an ebuild

qlist vim

Looking for packages with the 'firefox' USE flag quse firefox or with description quse firefox -D

Having done stupid things

You sit in front an half dead computer and the previous last hope solution does not work. All you get are error messages and not much is working anymore. Pretty dumb feeling isn't it? I know that well. So you have a broken system. Maybe you know what damage has been done, maybe not. Maybe you unmerged a system ebuild?

So keep in mind for next time: Never ever unmerge system ebuilds!

The system is a set of programs used to do emerge, fetch and install data from the Internet. Reasons why things like that can happen are often updates that fail, having tried to fix the problems make the things worse and try to revers the action made make it even more worse.

Now some hints for the case when the last hope solution failed. For such cases you probably need a second preferably Gentoo computer.

Emerge still does not work

You get still an error when you do emerge -a --oneshot libtool. Probably you can not fetch the file from the Internet. Go to a second well running Gentoo computer and emerge --fetchonly libtool then copy it to a memory stick and go to the broken computer mount the stick and copy the file to /usr/portage/distfiles. Now try again emerge -a --oneshot libtoolemerge should now proceed well. However emerge -e system will fail (See: Creating a script with packages necessary). On the second well running Gentoo computer delete all files in /usr/portage/distfiles and then do emerge --fetchonly -e system so you get all necessary files in /usr/portage/distfiles to fix a system. Copy all files in /usr/portage/distfiles to a (Gigabyte) memory stick (or even burn a CD or DVD), go to the broken computer, mount the stick and copy all files to /usr/portage/distfiles then run emerge -e systemand your system should be fixed after having emerged a couple of hundred ebuilds. Try now the following three lines to check if everything is now OK:

emerge --update --deep --newuse world

emerge --depclean

emerge @preserved-rebuild

Repairing a broken system

If you have a badly broken system where you can not log in, start commands and access the drives then the following can resolve the problem quickly. Used a live CD or DVD as to have something nice to work as KDE. In go to releases/x86/2008.0/stages

directory and download stage3-i686-2008.0.tar.bz2 that contains all necessary files to have a system. Unzip it in some directory somewhere on the hard disk. Avoided to copy over the directories /var and /etc since there are the settings and the database containing all you have installed. Copy the directories inside (/bin /lib /usr) over to the broken system without deleting something there. Then do the periodic maintenance task as emerge --sync, emerge --update --deep world, ... .

Repairing a broken portage

If you have a system where you can not launch emerge commands then the following can resolve the problem quickly. Used a live CD or DVD as to have something nice to work as KDE. In go to the snapshots

directory and download portage-<nnn>.tar.bz2 that contains all necessary files to have a running portage. Unzip it in some directory somewhere on the hard disk. Copy the directory bin to /usr/lib/portage/bin. Then emerge sys-apps/portage.

Last hope solution to fix a broken installation

  1. Check if gcc is ok gcc-config -l. See and that they correspond with /etc/portage/make.conf. If not emerge gcc and maybe rebuild your kernel with the new gcc. The root of many big problems comes from there, Cflags are confusing so take the time to set them once the way you want, and don't touch them afterwards.

  2. Check if the file /var/lib/portage/world is not full of garbage. If so delete the files not necessary

  1. emerge -a --oneshot libtool (one shot makes that it will not be registered in the world profile for later updating.

  2. emerge -e system

  3. emerge -e world

  4. emerge -a --depclean

  5. emerge @preserved-rebuild

In steps like emerge -e system or emerge -e world a lot of packages will be compiled and there is a rather high possibility that one out of hundreds packages will fail probably due to a use flag setting. To avoid that it has to be started again from the beginning:

  1. Use emerge with the --pretend option and direct the output in a file.

    emerge -e -p system > systemscript

  2. Modify the file in a way that it becomes a bash script. Using an editor replace

    [ebuild R  ] 


    emerge =

    and other lines. Delete eventually USE flag information. The result of the bash script would typical look like:

    emerge =dir/ebuild-version
  3. Give executable rights to the bash script and run until it fails or passes. If the bash script failed, wipe off the part that passed troubleshoot and restart it. If it failed due to a use flag adjust it using ufed and

    emerge --update --deep --newuse world

  4. Repeat until all packages have been completed

emerging sets

Lists of ebuilds can be created and are called a set. The @ character is used to know if it is an ebuild or a set. Historically worls and system get also understand as set when the @ character is missing, The user can also create sets. Those sets are put in files and stored under /etc/portage/sets.

A optimist does emerge -e @world. There is a change that one of the package fails after hours of compilation and if this happen uncertainties is what has successfully compiled and what not. elogviewer is a good help. It is therefore a better approach to create a set of ebuilds to be be emerged. and then deleting the ebuilds successfully emerged and then repeat those steps until every work is done.

emerge -pve @world > /etc/portage/sets/eworld would create file containing all ebuilds to be emerged. Unfortunately there is more information than emerge requires and would make syntax errors. This information can be removed by sed or with some manual work by libreoffice calc and sed: Open eworld as csv with blank as separator.

Check that all ebuilds are on the same column.

Delete all columns except the one with the ebuilds.

Insert a first column and enter there > in all rows.

Save it as eworld2.csv

then run sed 's/< /=/' <eworld2.csv >eworld3

and finally emerge -1 @eworld3


The ebuilds emerged with the set are not added to /var/lib/portage/world, they are added as set to /var/lib/portage/world_sets

Fixing with binary packages

Binary packages for gentoo can be put under /usr/portage/packages and the subdirectory of the category (e.g. /usr/portage/packages/sys-devel/usr/portage/packages/sys-devel) after adding


in /etc/portage/make.confand running env-update && source /etc/profile then emerge -K <packetname> or emerge --usepkgonly <packetname>

When a gcc gets installed this way then CHOST must match. Then it needs to be activated with gcc-config -l

Linurs Servernest startpage