Foolproof Gentoo World Update Build Order

Users new to Gentoo often end up breaking their system after their first global package update - particularly if they stopped reading the manual as soon as they got their system booting (I'm usually one of those). Over the years I have run into every problem that portage can imaginably throw at a person and from that I have formulated a fool-proof update process which, sometimes with a little intervention, always works and - assuming you take proper care of configuration - leaves you with a working system.

The first thing you need to do is think of any software you have installed where a version change might break something, for example: some fglrx driver versions will work with old cards and Xinerama, and some will not - in no particular order. I had the unfortunate experience of blindly upgrading my fglrx implementation to one that didn't work only to find the version I had been using was no longer available in portage. Use quickpkg to make a quick standalone package of the existing files for a given atom:

# quickpkg cate-gory/package-name

The package will be available for later use in /usr/portage/packages.

Now let's update portage:

# emerge --sync

If you are given a message instructing you to update the portage package it is important that you do so before continuing.

# emerge portage

Before we begin compiling anything I need to point out that if you use certain CFLAGS some packages may fail to compile. I always include -fstack-protector which adds buffer overflow protection to software at compile-time. Glibc in particular tends to have a problem with this feature. Updating world with this flag in would break the long update process when emerge gets to glibc and we want the newest GCC suite available to compile the rest of our system anyway - so let's update glibc and gcc separately from world, and if we encounter any problems we'll temporarily strip down our CFLAGS:

# emerge --update gcc glibc

Now we want to make sure your profile is set to use the latest version of GCC available on your system, it might look something like this:

# gcc-config -l
[1] x86_64-pc-linux-gnu-4.1.2 *
[2] x86_64-pc-linux-gnu-4.3.4

The asterisk indicates which version of GCC you are using. You can set the version by running gcc-config number where number is in the leftmost position of the output above, thus:

# gcc-config 2

You will be instructed to update your profile environment variables:

# source /etc/profile

It should be noted here that some software may not compile correctly with a given GCC version, requiring you to move up or down. At the time of writing Quemu requires GCC 3x and I have had a few isolated incidents of Xen being picky.

Before we get started let's launch a screen instance (emerge screen if you have not already done so) so we can move from terminal to terminal without interrupting the build process:

# emerge screen
# screen -S update

You can detatch from the session with the key combination control+a, d. Returning to the session is as simple as logging in from anywhere as the user who spawned the session and typing:

# screen -x update

Multiple clients may attach to the same screen session at once. This is particularly useful if you want to be able to orchestrate some or all of the upgrade over secure shell.

Now we're ready for the magic line:

# emerge --update --newuse --deep world --ask

Recent versions of portage have excellent automatic blocked package resolution, but it doesn't work all the time. If you can't continue due to blocked packages try to emerge either package one at a time. This often isn't enough - particularly where one package has taken over "duties" for the same files an existing package used to provide. In these cases you will have to unmerge one or both of the conflicting packages - but sometimes unmerging the wrong one(s) may leave your system unusable. Google the package names and version numbers; without fail I have always found someone on the Gentoo bugtraq and elsewhere who has had the same problem and someone has usually posted the safest order of removal. Of course, nothing can't be fixed by booting with the livecd.

If you get strange errors about file collision protection but you're sure it's safe to overwrite the listed files, you may add this line to your make.conf or precede your emerge command similarly:


If you will be unable to attend the update process (going home for the weekend etc) you may find it useful to add --keep-going to the emerge flags; this will skip over packages that fail to build and continue emerging. If you can't tell from the error messages repeated at the end of the build simply re-run the emerge command, making sure to use either --ask or --pretend and the missing packages will be neatly listed.

Often enough these packages fail to compile due to a missing reverse-dependency. The next stop on the line is revdep-rebuild, run simply:

# revdep-rebuild

This tool will scour your system for missing reverse dependencies, build a list then start compiling them if it finds any. This process can fail if it attempts to rebuild a package for which there is no longer a matching version in portage, in which case you may have to do some emerging/unmerging/updating of the given package's dependants. If the builds themselves fail it is safe to move on to the next step then return to revdep-rebuild later.

Python is an integral part of the gentoo system so it is very, very important that when python is updated the python-updater tool is run:

# python-updater

If you just upgraded PERL, be sure to run:

# perl-cleaner all

Which will take care of removing old header files, renaming files and rebuilding perl modules. It usually ends up rebuilding net-snmp on my systems and not much else in the way of ebuilds.

Lafilefixer fixes libtool archives and may not be needed on your system (does not come installed by default, emerge lafilefixer if you have not already) but it won't hurt to run it:

# lafilefixer --justfixit

Even if your first revdep-rebuild worked it is a good idea to run it again, in case any of the (possibly) newly installed packages have broken anything else. If some packages failed to build in the first world update you may now run it again.

It is now safe to clear out your old dependencies - should any exist. Most of the packages you will see listed are simply old versions of updated packages as a number of them occupy slots (such as GCC) for the sake of backwards compatibility. If you would like to retain a specific package, add it to your /var/lib/portage/world file, in full if you would like to target a specific version: =categ-gory/package-name-version.number

# emerge --depclean --deep --ask

Do not forget to update your configuration files. Be warned that simply overwriting all of the old configuration files may not be necessary and may render your system inaccessible:

# etc-update

That concludes my foolproof build order. If you followed it correctly there is a high probability your system is completely up-to-date and working, from a portage point of view. Of course, proper configuration is important and compile-stopping bugs are common and may require some mild footwork, but this usually amounts to copying and pasting the first error line into google or blocking/unblocking specific package versions with /etc/portage/package.mask, package.keywords and package.unmask. More information on package masking is available in the emerge man page.

Happy building!


• Argief

Agree with all your comments, however on gentoo.org the only current documentation I can find for upgrading is "An Introduction to Portage" which is part of the Handbook.

I mean no disrespect and although the Introduction to Portage is well written, I find it "informative" at best. After running gentoo for more close on 3 years, I now understand alot of what the author of Introduction to Portage is trying to say. But as a brand new user, there was so much to learn that I barely understood a word. I think both you and me know gentoo upgrades are not for the faint hearted... When you have no X installed, it's pretty much painless. But with X installed you will more often than not run into a few obstacles...

Your advice on upgrading, specifically revdep-rebuild/perl/python/lafilefixer has saved me a couple of times. I can't find a similar documentation project on gentoo.org and would LOVE to see your contribution there! Don't sell yourself short, it is REALY well explained/documented and deserves to be shared with a broader community.


I should also mention I'm sure the folks at Gentoo.org would much prefer you follow the actual documentation rather than a quick-and-dirty guide like mine because having users know all the nuances saves them headaches :p


Thank you for the high praise!

I personally wouldn't recommend doing any sort of un-monitored update in a production environment because there are any number of things that can go wrong.

Though rebooting isn't usually necessary there are cases where, for instance, a new version of udev may get installed and cause problems with an old kernel.

It is important to know what software has been updated because stale libraries and binaries will stay active until they have been re-loaded (often that means re-starting the software).

It is also important to remember that starting some software with outdated configs (i.e. if your machine crashes or you reboot it before running etc-update) may lead to unexpected behaviour or fail flat-out. Re-starting everything live or doing a reboot is the only way to know for sure that everything will come up quickly and as expected after a catastrophic failure.

For example, I recently had a very serious problem with apache because i simply dragged an old version of php.ini around for too long: http://foxpa.ws/2012/08/12/apache-reload-fix-seg-fault-or-similar-nasty-error-detected-in-the-parent-process/

• Argief

Hi, it's me again. I REALLY come here often. Again, I want to say I have learned SO much from this, but I find myself here again! Every time I come here, I get scared when the page loads slow I'm afraid that you have taken it down! Please, can I ask you to post this on gentoo.org. I cannot think how you can survive an upgrade the first few times, if you don't have this valuable guide to get you through it. THIS guide changed my LIFE and I am forever committed to gentoo, all thanx to you!!! I remember there was a time when I ONLY upgraded at 60 to 90 days, because my system would ALLWAYS be down and I would struggle to get it fixed again for days and days on end! Now I have converted your wisdom above to bash script and I do an UNATTENDED gentoo upgrade on a VPS to which I only have ssh access. I have absolute faith in this script I dont even care I KNOW it will work perfectly I am not even afraid to reboot. I have posted the script below, maybe it could servers as faithfully as it does me:

PS: I have added some stuff at the end, I like to keep it lean.



# Update portage
emerge -q --sync

# Update portage
emerge -qv portage

# Update gcc
emerge -qv --update gcc glibc

# Update environment
source /etc/profile

# Update system # use -p for pretend
emerge -qv --keep-going --update --newuse --deep --autounmask-write world

# Rebuild broken libraries

# Update python

# Update perl
perl-cleaner all

# Remove old source files
eclean distfiles

# Remove all binaries
eclean packages

# Check world file for problems
emaint --check world

# Fix world problems
emaint --fix world

# NB REMEMBER etc-update!!
# etc-update

# Try dispatch-conf?? replacement for etc-update??

# Clean-up:
# emerge --depclean --deep --ask && revdep-rebuild

• Argief

This is the best write-up I have found. I refer to it EVERY time I do a gentoo update. It works 99.9% of the time! I been using this for almost a year. I keep meaning to write a script that would do this process, but I just have not as yet gotten to it. Thank you SO much for sharing this experience!


Thank you, it's really nice to hear you found it useful :)

• Adhulma

Really aproved.]
Thanks a lot.