Per-Package USE Flags in Gentoo: Overriding Global Settings Without a Full Rebuild

When Global USE Flags Force an Unwanted System-Wide Rebuild

Gentoo's Portage system compiles software from source, and USE flags decide which optional features are included in the final executable. A common problem arises when your global configuration in /etc/portage/make.conf disables a feature, but one specific package needs it enabled. Changing the global flag tells Portage to recalculate the entire system dependency graph, often triggering rebuilds across many unrelated packages. The targeted solution is a per-package override in /etc/portage/package.use, which changes the build for only the package you name.

This approach reduces binary bloat and minimizes the attack surface by excluding unnecessary code from every package except the one that genuinely needs the exception.

How Portage Merges Global and Per-Package Flags

USE flags are compile-time toggles. An ebuild—the script that builds a package—reads these flags to decide which optional dependencies to pull in and which arguments to pass to the build system. Portage evaluates flags during dependency calculation, before any compilation begins.

Portage reads two main sources for these toggles:

• Global flags: defined in /etc/portage/make.conf under the USE variable. These apply to every package on the system.
• Per-package overrides: defined in /etc/portage/package.use or in files inside the /etc/portage/package.use/ directory. These apply only to the package atom listed on each line.

When both sources define a flag, the per-package entry wins for that package. This lets you keep a minimal global set while making exceptions for individual applications. The merged set determines which optional libraries are linked, which kernel features are exposed, and which code paths are compiled into the binary.

Example: Adding Wayland Support to a Single Browser

Suppose your global USE flags exclude wayland to keep the system focused on X11, but you need app-chrome/chrome to build with Wayland support. As root, edit or create /etc/portage/package.use and add a line using the package atom followed by the flag:

app-chrome/chrome wayland

Then reinstall the package. Portage merges the global flag set with this local override only for app-chrome/chrome. Other packages continue to build without Wayland, and the system-wide dependency graph remains unchanged. This keeps the rest of the system lean while giving the browser the backend it requires.

If you prefer to keep overrides in separate files, you can instead create a file such as /etc/portage/package.use/chrome containing the same line. Portage reads both the single file and the directory, so either layout works.

Limits and Common Mistakes

Per-package overrides are powerful, but they have hard limits.

Invalid or Unsupported Flags

If the ebuild for that package version does not define the flag you add, Portage may ignore it or emit a warning, but the feature will not appear in the compiled binary. Always confirm the flag exists for your installed version by checking the package's USE flag documentation.

Conflicting Flags

Some packages support mutually exclusive backends. Enabling both wayland and x11 when the ebuild expects only one can cause the configure script or compiler to fail. Read the package's USE flag documentation before combining them.

Mandatory Dependencies

Disabling a flag that the package treats as mandatory can remove fallback code and break compilation. If a build fails after you remove a flag, check whether the ebuild requires it for basic operation.

Stale Builds

Editing package.use does not rebuild an already-installed package. You must reinstall the package for the new flags to take effect. Until then, the old binary remains on disk with its previous feature set.

Syntax and Placement Errors

A common mistake is placing per-package flags in make.conf using the wrong syntax, or adding them to package.use with an incorrect package atom. The atom must match the installed category and package name exactly. Extra spaces or missing slashes cause Portage to skip the line silently.

Verifying Active Flags and Build Results

After reinstalling, confirm that Portage applied the override. As a regular user, run:

equery uses app-chrome/chrome

This command, provided by app-portage/gentoolkit, lists the USE flags currently active for the installed package. Check that your target flag appears in the output. If it does not, verify that the package atom in package.use matches the installed version exactly.

To audit the global baseline, inspect /etc/portage/make.conf as root and review the USE variable. To confirm the compiler received the expected toggles, examine the build logs under /var/tmp/portage as root. These logs may be removed after a successful merge, so review them promptly if you need to diagnose a specific build.

A practical final check is to compare the output of equery uses before and after the reinstall. The only difference should be the flags you intentionally overrode for that package.