This is how I have been upgrading Gentoo for a long time. Is this the recommended method? Any gotchas or better methods to use?

emerge --sync
emerge -uDav --tree world
emerge -av --depclean
revdep-rebuild -v -- --ask
glsa-check -t all
glsa-check -f all
  • 6
    I add the -N flag onto emerge personally
    – Tom Ritter
    Commented May 19, 2009 at 17:00
  • 2
    --tree (-t) is also handy for understanding what's going on
    – lkraav
    Commented Aug 1, 2011 at 5:12

10 Answers 10


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

  • 2
    Yep, definitely +1 on keeping up to date on the regular rather than in huge chunks. There are the occasional changes that just break a lot. github.com/lkraav/gentoo-cron-weekly is my simplistic weekly reporting toolset.
    – lkraav
    Commented Aug 1, 2011 at 5:15

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

  • 1
    If you stick to unmasked ebuilds then Gentoo has become quite stable in my opinion and doesn't every really break by doing a sync and emerge world. You do need to know what you are doing but the same can be said for apt or yum. I've been bitten by them both. Commented May 19, 2009 at 16:12
  • 1
    Three very recent blockages/breakages I can think of are libcomerr/e2fsprogs, firefox2/3, and xorg 1.3/1.5. In all those cases it took non-trivial massaging to make the wholesale update work, and there were no ~keywords involved. Commented May 19, 2009 at 16:28
  • 2
    The latest versions of portage - say within the last 6 months - automatically resolve nearly all blocks and breaks. Including libcomerr/e2fsprogs.
    – Dan Carley
    Commented Jun 10, 2009 at 6:39
glsa-check -t all
glsa-check -f all

That's what you should run first. It's unneeded if you upgrade all the packages.

Oh and I prefer cfg-update ;)


This is what I do:

emerge --sync         //Synchronize the package manager with the latest 
                      //version of each package.

emerge -aDvNu system  //updates the system, but only important if you want the
                      //latest stable version of the actual compiler and libraries
                      //with the core system.

emerge -uDNav world   //world means everything we've asked to be emerged before
                      //this does not include things that came pre installed.
                      //N means if you change your use directives in 
                      //your make.conf file to pull in the new packages.

emerge -av depclean   //removes libraries or programs that don't have any other 
                      //dependencies because of an update.

revdep-rebuild        //means if something is broken by an update, it 
                      //recompiles it.  Fixes dynamic and static linking problems.

If you don't completely understand the comments, read this because it is the authority on how to update your gentoo packages.



Your process is correct though running every command is probably not necessary usually I just do a sync and an update world. Emerge will tell you usually if you need to run a script to rebuild file such as during a major Python upgrade and will also tell you when to merge configuration changes. Since Gentoo doesn't actually have an upgrade path from version to version. The moment you emerge world you've got the latest version.


For a long time now I always used this procedure:

emerge -f --update --newuse --deep world && emerge --update --newuse --deep world

I, for mine, prefer to update over night. But sometimes it happens that something fails and so you have to download all (or some) programs again.

Perhaps the --newuse switch is unnecassary, but I'm often editing my make.conf so it makes sense for me.

  • You can use "--reinstall changed-use" instead of "--newuse", this reinstalls packages with use flags that you have explicitly changed. Instead of obsoleted, added use flags etc. You should still run with "--newuse" from time to time though.
    – hayalci
    Commented Jul 3, 2009 at 22:20

Looks fine, although I wouldn't be so quick to run depclean.

Unless you have a requirement like low HDD space then you can come back and depclean at less regular intevals. There's no harm having them around for a short period. If you were unlucky enough to notice some broken packages after the update then you would be sure that they aren't a result of removing any loose dependencies.


That's the way I do it on my VPS:

step 0 (from /etc/crontab)

0 0   * * *     root    emerge --sync &> /dev/null

step 1:

emerge --update --deep --newuse world -av

step 2:

emerge --depclean && revdep-rebuild && eclean-pkg && rm /usr/portage/distfiles/*

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .