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 (-j or --jobs) some ebuilds do just emerge with MAKEOPTS -j1

or MAKEOPTS="-j1 -l1" emerge -1 sys-apps/coreutils (-l or --load-average) to restrict the average load too.

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 /var/cache/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.

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/lib64/perl5 where the installed versions can be seen.

Special updating perl procedures might remove lots of perl emerge problems. Commands for that are perl-cleaner --all or 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. Check if dmesg shows running 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<?>.

Or consider to emerge binary packages as emerge rust-bin and emerge firefox-bin

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

Gentoo has multiple python versions installed ls -l /usr/bin/python* shows it. The Gentoo system uses python for its scripts as emerge. The used python version must not be necessary the newest version. The combination newest version and actual scripts might be not stable enough.

Gentoo uses python-exec a wrapper that selects one from the installed versions

eix --installed-with-use python_targets_python3_7 or emerge -cp python:3.6 will show the packages installed per python version

grep -r python3_6 /etc/portage/package.use* will show if some packages are installed the require a dedicated python version.

Check that python packages (as: pycairo, pygtk, ... ) get install using the right python version /usr/lib/python<n.m>/site-packages/.

Decide on the python version unmerge the not used python version might be dangerous since system packages might become unavailable.

A regular user does not need too many different python versions active.

Gentoo might get confused about different versions and might run in dependency problems or missing python libraries.

To help the installation create touch /etc/portage/package.use/python and add the useflags for all python packages for the current versions and the current single target version

emerge --depclean

emerge -1vUD @world

*/* PYTHON_TARGETS: -* python3_9 python3_10
*/* PYTHON_SINGLE_TARGET: -* python3_9

emerge --depclean

update /etc/portage/package.use/python

emerge -1vUD @world

emerge --depclean

*/* PYTHON_TARGETS: -* python3_9 python3_10
*/* PYTHON_SINGLE_TARGET: -* python3_10

emerge --depclean

update /etc/portage/package.use/python

emerge -1vUD @world

emerge --depclean

*/* PYTHON_TARGETS: -* python3_10
*/* PYTHON_SINGLE_TARGET: -* python3_10

comment the lines in /etc/portage/package.use/python to have them ready fro the next python update.

emerge -1vUD @world

emerge --depclean

After that emerge --update --newuse --deep --with-bdeps=y @world then adapt it to the new updated versions and do emerge --update --newuse --deep --with-bdeps=y @world again. Finally comment the /etc/portage/package.use/python and do again emerge --update --newuse --deep --with-bdeps=y @world

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

Having done stupid things

Sitting 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.

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 or elogv are good helps. 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

Linurs startpage