Gentoo's Three Rebuild Tools: --changed-use, @preserved-rebuild, and preserve-libs

You flip a USE flag in /etc/portage/make.conf, run an update, and suddenly a service won't start. Or a glibc upgrade lands and half your system throws linker errors. Gentoo's source-based model gives you control, but it also means you are responsible for keeping installed packages consistent with the libraries and build options they were compiled against. Portage offers three supported mechanisms for this: --changed-use, the @preserved-rebuild set, and the preserve-libs feature. Knowing which one to reach for—and when to preview before committing—is the difference between a clean maintenance window and a broken afternoon.

USE flag changes and --changed-use

Portage records the effective USE flags for each installed package in its database, typically under /var/db/pkg. When you change a global or per-package USE setting, those recorded values no longer match what the ebuild would produce today. emerge --changed-use compares the recorded state with the current configuration and rebuilds only the packages whose effective flags differ.

Run this as root to preview the closure:

emerge --pretend --changed-use --deep --with-bdeps=y @world

The --deep flag includes the full dependency closure, and --with-bdeps=y pulls in build-time dependencies so that packages built against a changed library are not missed. Because that closure can be large, always preview with --pretend first. If the list looks reasonable, run the same command without --pretend.

Important limitation: --changed-use rebuilds the package whose own USE flags changed, but it does not automatically rebuild reverse dependencies that were compiled against a different build of that package. If you change the USE flags of a library, consumers of that library may still need attention.

Library ABI changes and @preserved-rebuild

When a package updates a shared library and its soname—the binary interface identifier embedded in the .so filename—changes, every package that linked against the old soname must be relinked. The old external tool revdep-rebuild is deprecated; modern Portage handles this through the @preserved-rebuild set.

Run as root to check what needs rebuilding:

emerge @preserved-rebuild --pretend

If the output lists packages, those consumers linked against libraries whose ABI changed during the last update. Commit with:

emerge @preserved-rebuild

This is the standard follow-up after a major system update—especially after a glibc upgrade—to catch breakage that emerge -uDN --with-bdeps=y @world did not resolve on its own.

preserve-libs as a safety net

Recent Gentoo profiles enable preserve-libs by default. When a library is updated, Portage can preserve the old version on disk and track which packages still link against it. This delays the need for an immediate full reverse-dependency rebuild, giving you a window to test and schedule the work.

Verify it is active (run as root, or as any user who can read Portage's configuration):

emerge --info | grep -E 'FEATURES|preserve-libs'

The trade-off is that preserve-libs can mask ABI breakage. A program may continue running against the preserved old library while its peers have already moved on, hiding an incompatibility until later. After significant library updates, test critical applications rather than assuming the preserved library makes everything safe.

A worked maintenance sequence

Imagine you have just run emerge --sync, read pending news with eselect news list, and you are ready to update. You also recently added a global USE flag to /etc/portage/make.conf. The safe order matters.

1. Preview the USE-flag rebuild closure (root):

   emerge --pretend --changed-use --deep --with-bdeps=y @world

   Review the list. If it is unexpectedly large, consider narrowing the scope or scheduling a maintenance window.

2. Perform the world update (root):

   emerge -uDN --with-bdeps=y @world

   The -u updates packages, -D considers the full dependency tree, and -N includes packages with changed USE flags—overlapping with --changed-use but ensuring nothing is skipped.

3. Check for preserved-library consumers (root):

   emerge @preserved-rebuild --pretend

   An empty list means no installed package is still linked against a preserved ABI. A non-empty list means those packages need rebuilding; commit with emerge @preserved-rebuild.

4. Verify features and config:

   emerge --info | grep -E 'FEATURES|preserve-libs'

   Confirm preserve-libs appears in FEATURES if your profile expects it.

If a critical service fails to start after the world update, check whether it links against a preserved library before debugging the application itself.

Trade-offs and practical limits

--changed-use combined with --deep can rebuild far more than you intended. A single global USE change can touch hundreds of packages. Use --pretend and, when possible, package-specific package.use entries to limit scope.

Changing USE flags on a running system can leave services inconsistent until the rebuild completes. Plan maintenance windows for large closures.

preserve-libs is a delaying tactic, not a permanent fix. Eventually the preserved libraries must be cleaned up, and until then disk space and runtime behavior may diverge from a fully rebuilt system.

A practical checklist

• emerge --sync as root.
• eselect news list and read anything relevant.
• Preview: emerge --pretend --changed-use --deep --with-bdeps=y @world.
• Update: emerge -uDN --with-bdeps=y @world.
• Follow up: emerge @preserved-rebuild --pretend, then commit if needed.
• Test critical services.

Gentoo does not guess your intent. These three tools let you express it precisely—changed build options, changed binary interfaces, and a temporary safety net—so your system stays coherent without rebuilding the world every time.