Controlling Gentoo Build Features with Portage USE Flags

The problem: a USE flag rebuilds more than you expected

You run emerge --update @world and Portage suddenly wants to rebuild media-libs/freetype, media-libs/fontconfig, and a dozen libraries you did not touch. The cause is usually a USE flag: a boolean variable that tells an ebuild whether to compile an optional feature such as SSL, Bluetooth, or X11 support. Portage recalculates the dependency graph whenever an effective flag changes, which can pull in reverse dependencies—packages that depend on the one you modified.

The practical takeaway is that you control these flags. You can set them globally in /etc/portage/make.conf or per package in /etc/portage/package.use, preview the impact before anything compiles, and verify the result with equery uses.

Where USE flags are configured

Portage is Gentoo's package manager. An ebuild is the script that describes how to build a package. The @world set contains the packages you explicitly installed plus their dependencies.

Global flags go in /etc/portage/make.conf:

USE="ssl X bluetooth"

Package-specific overrides go in /etc/portage/package.use, which can be a single file or a directory of files. A directory is easier to maintain because each package can have its own file.

Worked example: enable SSH2 for curl only

Suppose you want net-misc/curl built with SSH2 support, but you do not want the ssh2 library pulled into every package that happens to support it. Run these commands as root on the Gentoo host.

1. Add a package-specific override. If /etc/portage/package.use is a directory, create /etc/portage/package.use/curl:

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

1. Preview the dependency changes without installing anything:

emerge --ask --newuse --deep --verbose @world

Look for net-misc/curl in the output. The USE column should show ssh2 added, and any newly required dependencies should appear before you confirm. --newuse tells Portage to include packages whose effective flags changed; --deep walks the full dependency tree; @world limits the operation to your explicit set.

1. If the preview looks correct, confirm the merge. Afterward, inspect the effective flags:

equery uses net-misc/curl

equery is provided by app-portage/gentoolkit. It prints the USE flags Portage actually used for the installed package, which is the authoritative check.

You can also confirm the configuration files directly:

grep -R "net-misc/curl" /etc/portage/package.use /etc/portage/make.conf

Trade-offs and limitations

Enabling too many global USE flags increases compile time and can pull unwanted optional dependencies across the system. Inconsistent flags—for example, rebuilding a library without ssl while a dependent package still expects it—can cause missing symbols at runtime. Profile changes can also alter default flag values, so a system updated after a profile switch may see unexpected rebuilds.

Prefix installations or non-standard Portage layouts may store configuration in different paths, so verify your layout before applying these examples.

Undoing a change and checking the result

Because editing package.use and running emerge changes system state, there is no one-click rollback. To undo the curl example, remove the ssh2 line from /etc/portage/package.use/curl and run:

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

Portage recalculates the effective flags and drops ssh2 from curl unless another installed package still requires it. If you want to remove now-unused dependencies, review emerge --depclean carefully before running it, since it can remove packages other software depends on.

Practical verification after any change:

• equery uses <category/package> to confirm effective flags.
• emerge --ask --newuse --deep --verbose @world to preview before committing.
• tail /var/log/emerge.log to review what was actually built.

Start with package-specific overrides rather than global flags, preview every change, and verify with equery before assuming the build is complete.