Gentoo USE Flags: Practical Configuration and Common Pitfalls

The Problem and the Takeaway

You need to customize package features—enabling PipeWire support in a media player, disabling Bluetooth on a headless server, or choosing between OpenSSL and LibreSSL—without maintaining local patches or overlays. Gentoo's USE flags solve this by letting you toggle optional features at compile time through Portage. The catch: flags cascade across the dependency graph, so a single change can trigger dozens of rebuilds. Disciplined flag management—scoped definitions, preview before apply, and mandatory world updates—keeps the system consistent and compile times reasonable.

How USE Flags Work

Each ebuild declares a set of optional features (USE flags). When Portage computes the install plan, it evaluates the active flag set for that package and passes corresponding options to the build system (meson, cmake, autotools, etc.). Flags are boolean: flag enables, -flag disables. Portage also enforces REQUIRED_USE constraints—e.g., || ( alsa pulseaudio ) means at least one audio backend must be selected.

Flags are resolved in this precedence order (highest wins):

1. Per-package entries in /etc/portage/package.use/ (files or directory)
2. Global defaults in /etc/portage/make.conf (USE="...")
3. Profile defaults from /var/db/repos/gentoo/profiles/

Changing flags does not rebuild packages automatically. You must explicitly request a rebuild with --newuse.

Worked Example: Headless Server Profile

Scenario: a minimal server running only SSH, nginx, and PostgreSQL. No graphical stack, no Bluetooth, no PulseAudio. We'll define a clean flag set in make.conf and add per-package overrides for nginx and postgresql.

1. Global flags in /etc/portage/make.conf

# /etc/portage/make.conf
USE="-X -gtk -qt5 -kde -bluetooth -pulseaudio -pipewire -systemd"
USE="${USE} ssl openssl"
USE="${USE} postgres"
MAKEOPTS="-j$(nproc)"
FEATURES="parallel-fetch buildpkg"

Notes:

• Flags are space-separated. Missing spaces (e.g., -X-gtk) are a common syntax error.
• Negative flags (-X) disable the feature globally unless a per-package entry re-enables it.
• ssl openssl selects OpenSSL as the TLS provider (profile may default to LibreSSL).

2. Per-package overrides in /etc/portage/package.use/server

# /etc/portage/package.use/server
www-servers/nginx http2 ssl threads -http-cache -vim-syntax
dev-db/postgresql server -doc -ldap -kerberos -pam -ssl -uuid

Here we enable http2 and threads for nginx while disabling optional cache and syntax highlighting. For PostgreSQL we keep only the server USE flag (pulls in the server binaries) and drop documentation and auth modules we don't need.

3. Preview the changes

Run as root in a shell with Portage access:

emerge -pv --update --deep --newuse @world

Expected output shows each package with [ebuild N ] (new install), [ebuild R ] (rebuild), or [ebuild U ] (upgrade), plus the USE flag string in brackets. Verify that:

• No REQUIRED_USE violations appear (Portage will error if they do).
• Rebuild count is acceptable—dozens is normal for a global -systemd flip; hundreds suggests a flag conflict.
• Critical packages (glibc, gcc, kernel) are not slated for rebuild unless you changed toolchain flags.

4. Apply the changes

emerge --ask --update --deep --newuse @world

Watch the build logs. If a package fails due to a flag combination (e.g., nginx[http2] requires ssl), Portage stops and prints the unmet REQUIRED_USE. Adjust the flag file and re-run.

Limits and Trade-offs

Compile time and binary size

Every enabled flag adds code paths, dependencies, and compiler work. A desktop profile with wayland pipewire bluetooth can double the package count versus a minimal server. On modest hardware (4-core, 8 GB RAM), a full @world rebuild after a global flag change may take 6–12 hours. Mitigations:

• Use FEATURES="buildpkg" and a binary package host (binhost) to share compiled packages across machines.
• Restrict global flags; prefer per-package overrides so only affected packages rebuild.
• Schedule large rebuilds during maintenance windows.

Flag conflicts and REQUIRED_USE

Ebuilds declare constraints like REQUIRED_USE="^^ ( alsa pulseaudio pipewire )" (exactly one). If your global make.conf sets -alsa -pulseaudio -pipewire, Portage will refuse to build any package with that constraint. The fix is to enable one backend globally or per-package. Always run emerge -pv after flag edits to catch these early.

Profile interactions

Choosing a profile (e.g., default/linux/amd64/17.1/desktop/plasma) sets baseline USE flags. Overriding profile defaults globally can fight the profile's intent. Better: select a closer profile (server vs desktop) and layer only necessary overrides.

Common Mistakes

Mistake	Symptom	Fix
Missing space between flags	USE="-X-gtk" parses as one flag	Always separate with spaces: USE="-X -gtk"
Contradictory flags in same scope	USE="alsa -alsa" — last wins silently	Audit make.conf and package.use/* for duplicates
Forgetting --newuse	Packages keep old features after flag change	Always include --newuse when flags change
Skipping --deep	Dependencies not rebuilt, runtime mismatches	Use --deep for full dependency tree
Editing flags mid-emerge	Inconsistent state, partial rebuilds	Finalize flags, then run single emerge command

Verification Checklist

1. Inspect active flags for a package: emerge -pv / shows the resolved USE string.
2. Check for unsatisfied constraints: emerge --pretend --update --deep --newuse @world 2>&1 | grep -i required_use.
3. Confirm world consistency: After rebuild, run emerge --depclean -p to ensure no orphaned packages remain due to flag changes.
4. Validate runtime: For critical services (nginx, postgresql), run their self-tests or connect to verify the expected features are present (e.g., nginx -V 2>&1 | grep http2).

When to Rebuild vs. When to Wait

Rebuild immediately when:

• Security-relevant flags change (e.g., ssl, hardened, pie).
• You added a required backend (e.g., enabling pipewire for a video conferencing app).

Defer rebuild when:

• Only cosmetic or optional flags flipped (documentation, examples, extra codecs).
• You're about to upgrade the profile or toolchain—combine into one rebuild cycle.

Summary

USE flags are Gentoo's primary customization lever. Define a restrictive global set in make.conf, layer precise per-package overrides in /etc/portage/package.use/, preview with emerge -pv --update --deep --newuse @world, and apply in a single transaction. Treat flag changes as a system-wide operation: verify constraints, accept the compile cost, and run --depclean afterward. The result is a lean, purpose-built system without downstream patches.