Gentoo USE Flags: Control Build-Time Features Without Unneeded Dependencies

Stop compiling features you will not use

Gentoo Portage builds packages from source, and many ebuilds offer optional features such as Kerberos support, Bluetooth, or printing. Each optional feature is controlled by a USE flag. Enabling flags you do not need pulls in extra dependencies and increases compile time. The supported way to manage this is to set system-wide defaults in /etc/portage/make.conf and override them per package in /etc/portage/package.use.

How Portage merges USE settings

Portage determines the effective USE flags for a package by combining profile defaults, the ebuild's IUSE declaration, global defaults from /etc/portage/make.conf, and per-package overrides from /etc/portage/package.use. Profile defaults apply first, IUSE defines which flags are valid for the package, make.conf sets the system-wide baseline, and package.use overrides per package. The final set is passed to the dependency resolver before any source is compiled. Per-package overrides take precedence over global defaults. A flag prefixed with - disables the feature; an unprefixed flag enables it. If a package does not list a flag in IUSE, Portage silently ignores that flag for the package.

Worked example: disable GSSAPI globally, enable for curl

Goal: avoid Kerberos/GSSAPI dependencies across the system, but keep GSSAPI support in net-misc/curl.

Edit /etc/portage/make.conf as root and add -gssapi to the global USE variable:

# /etc/portage/make.conf
USE="... -gssapi ..."

This is a system-wide default. Any package that declares IUSE gssapi is built without it unless a per-package override exists.

Create a per-package override. package.use can be a single file or a directory. Example file /etc/portage/package.use/curl:

# /etc/portage/package.use/curl
net-misc/curl gssapi

The line contains the package atom followed by the flags to enable for that package only. This overrides the global -gssapi for curl.

Before merging, preview the decision. Run as root:

emerge -pv net-misc/curl

Check the USE line shown for net-misc/curl. It should show gssapi enabled while other packages show it disabled. Do not merge until the preview matches your intent.

Verify the installed flags

After the package is installed, confirm it was built with the expected flags. With app-portage/gentoolkit installed, run:

equery uses curl

This shows whether gssapi is enabled for the installed instance. You can also inspect the metadata written at install time under /var/db/pkg, where each installed package records its USE variable.

Limits and common mistakes

Changing USE flags after installation can trigger rebuilds. Portage tracks changed flags with --newuse. Run as root:

emerge --deep --newuse @world

This rebuilds packages whose USE set changed and their reverse dependencies. A global change to a commonly used flag can cascade through many reverse dependencies because USE changes are treated as new version slots in the dependency graph. The operation can be large and time consuming.

Enabling a flag globally that a package does not declare in IUSE is silently ignored for that package. Conflicting flags can break builds or produce unexpected runtime behavior if a dependency expects a feature you disabled.

package.use syntax matters. An invalid package atom or malformed line can cause Portage to ignore the override or fail dependency resolution. Use a dedicated file per package for clarity. Disabling a widely used flag such as -ssl or -python can break packages that require it. Preview with emerge -pv first and check reverse dependencies with equery.