Optimal procedure to upgrade Gentoo Linux?

It seems like you've got it covered. The only other tip is to maybe take it a bit slower than a blind wholesale update. You can always update the packages or dependency chains individually with emerge -DNuav <atom> instead of world (use --oneshot for things you don't want to add in to the world file, like system libs for example).

Note that it's always easier to do if you keep up to date regularly rather than going for monolithic batch updates every couple of months. Also, to avoid too many surprises, you might find it helpful to subscribe to one of the mailing lists like gentoo-user (WARNING: ~100 mails a day on this list) since pretty much any major update issues are likely to show up on the list with plenty of discussion explaining how to solve them.

I would guess that the next major "problem" update will be the migration to openrc once it goes stable (it was done on ~arch middle of last year iirc with only a few issues, primarily with networking changes).


I've been using close to the same steps you do, except for:

  • eix-sync instead of emerge --sync because I like seeing the changes to the portage tree. This is especially nice for noticing packages I might want to install that are new to the tree.

  • layman -S (occasionally) before the main emerge to sync any changes in overlays.

  • eclean-dist -d after the revdep-rebuild to clean obsoleted tarballs. I do this after every emerge, because package downgrads aren't that common.

  • eix-test-obsolete as the last step to help keep my /etc/portage files tidy and up-to-date. This also lets me know when I have installed packages that have been completely removed from portage so I need to go get the ebuild from the repository. A recent example, I have to mask all versions of iproute2 > 2.6.22.20070710 due to the older kernel running on my Xen VPS but it was recently removed from portage.

eix-sync and eix-test-obsolete are in app-portage/eix.

eclean-dist is in app-portage/gentoolkit.


  1. emerge --sync or eix-sync or emerge-delta-webrsync and eix-update
  2. emerge -av portage
  3. eclean-dist

Check that one of linux-headers, glibc, binutils, libtool or gcc has major update (e.g gcc updates from 4.6 to 4.8). If it isn't go to the step 11.

Full rebuild:

  1. rm -rf $(portageq pkgdir)/* — cleanup cache in PKGDIR
  2. emerge -av linux-headers glibc binutils gcc-config libtool gcc
  3. gcc-config <number of new gcc> Switch to new gcc
  4. source /etc/profile
  5. emerge -avb glibc binutils gcc libtool
  6. emerge -avbke system
  7. emerge -avbke world

If you have any problem on step 10 or 11 then fix it and try again

Update world:

  1. Clean your world file /var/lib/portage/world from unnecessary packages and check /etc/portage entities
  2. fixpackages
  3. emerge -avuDN world
  4. eselect python update
  5. python-updater -- -av
  6. perl-cleaner --all -- -av
  7. emerge -a --depclean
  8. revdep-rebuild -i -- -av

If you have any trouble in steps 14-18 fix it and repeat all steps from step 13.

  1. etc-update or dispatch-conf
  2. glsa-check -vp affected You can have affected packages in slots after update
  3. emaint --check all

If your goal is to have the absolute latest of all packages, then yes, that seems to cover all the bases. I'm surprised this has worked for you for a long time, though, because I would imagine you'd get bitten often by blocks, broken deps, etc. In the last couple years I've become much more careful about wholesale updating, electing instead to do it piecemeal after viewing the update tree. Gentoo development seems to have passed its heyday. Maybe it's because of the rise of Ubuntu.

Anyway, one additional thing you might try, just to be really fastidious about the whole process, is cleaning out your distfiles. There are scripts out there if you search.