Taming Gentoo USE Flags Without Breaking Your System

The build finishes, the binary lands, and a headless server now drags in X11, PulseAudio, and a half dozen codec libraries it will never use. This is the classic USE flag surprise on Gentoo: a global default set months ago is still propagating through Portage’s dependency tree.

The useful takeaway is to treat USE flags as per-package policy, not global taste. Global defaults are convenient for a first install, but per-package overrides in /etc/portage/package.use keep the dependency graph honest and make the system auditable.

What USE flags actually change

USE flags are compile-time switches that ebuilds (Gentoo's package scripts) read to enable or disable optional features and their dependencies. Enabling ssl pulls in OpenSSL and links against it; disabling x11 removes X dependencies from a library that can run headless.

Portage propagates flags automatically. If package A requires package B with USE=foo, Portage will try to build B with foo enabled to satisfy A. This consistency is valuable, but it also hides why a feature appeared. Custom flags exist per ebuild and are not always listed in generic documentation, so the ebuild or upstream README is the authoritative source.

Global flags create invisible coupling

Flags set in /etc/portage/make.conf apply to every package unless overridden. This is easy to misuse.

# /etc/portage/make.conf
USE="-X -qt5"

A global -X will strip X support from editors, browsers, and tools where you might actually want it, while a global +qt5 can pull Qt into command-line utilities that only need it optionally.

Risk: over-disabling breaks functionality. Turning off ssl on a web server removes HTTPS support at compile time with no runtime warning. Misconfigured flags can also force Portage into version conflicts as it tries to satisfy incompatible USE requirements across the tree.

Worked example: limiting ffmpeg on a headless server

Goal: build media-video/ffmpeg with only the codecs needed for a transcode worker, without X11, ALSA, or GUI bindings.

First, preview the current plan from a terminal as a regular user:

emerge -pv media-video/ffmpeg

Check the dependency tree for X and audio libraries. To test a change without installing, simulate with a temporary flag override:

emerge -p media-video/ffmpeg USE="-x11 -alsa"

Run this as a user for simulation; actual installation requires root. Compare the dependency list before and after to see which libraries are dropped.

Make the decision permanent with a per-package override. Create a file in the package.use directory:

# /etc/portage/package.use/media
media-video/ffmpeg -x11 -alsa +opus

Using a directory like /etc/portage/package.use/ allows you to organize overrides by category. This overrides make.conf only for this specific package.

After installation, audit what was actually built:

equery uses media-video/ffmpeg

Run this as a user. Verify the enabled flags match your intent and compare the binary size against previous builds to confirm the reduction in bloat.

Trade-offs and limitations

Per-package control reduces compile time and binary size, which is critical on resource-constrained or embedded systems. It also prevents surprise dependency growth.

The cost is maintenance. A large package.use set is harder to review than a short make.conf. Because flags propagate, changing a flag on a core library can trigger a cascade of rebuilds for many dependent packages.

Rollback is only necessary if you change system state. If you installed a package with a bad flag set, revert the entry in package.use and rebuild the package using emerge -u @world or the specific package atom.

Close the loop with a regular audit: list packages with unexpected flags, simulate builds with different flags, and keep global USE minimal. This keeps Gentoo tailored without becoming fragile.