USE flags

Updated 7 November 2026

This page applies to Portage 3.0.82 and Calculate Utilities 3.8.

What are USE flags

The idea behind USE flags

When you install the system, you choose its contents to fit the environment you work in: a server configuration differs from a workstation, and a gaming workstation differs from a 3D rendering machine.

This is not only about the set of packages, but also about which features each package must support. If you do not need OpenGL, why install it and build support for it into most programs? If you do not use KDE, why build packages with KDE support when they work perfectly well without it?

USE flags are a short way to describe your working environment: they help you decide what to install and enable, and what not to. This way you decide for yourself what you really need, and Portage gets a convenient basis for useful decisions.

USE flag definition

A USE flag is a keyword that describes support for a feature and the dependencies related to it. When a flag is enabled, Portage assumes that the system administrator needs support for that feature. Enabling a flag changes the dependency information for a package: the requested support may require many additional dependencies.

Consider an example - the kde flag. If the word kde is not in the USE variable, or is listed with a minus in front (-kde), then all packages with optional KDE support are built without it, and packages with an optional dependency on KDE are installed without the KDE libraries. If the kde flag is enabled, those same packages are built with KDE support, and the KDE libraries are installed as dependencies.

Precisely set USE flags tailor the system to your needs.

Using USE flags

Permanent USE flags

All USE flags are listed in the USE variable. So that you do not have to build the list from scratch, the profile already defines a set of commonly used values - they are declared in the profile's make.defaults files.

The profile the system follows is set by the symbolic link /etc/portage/make.profile. In Calculate Linux this is the distribution profile from the distros repository: for Calculate Linux Desktop, for example, /var/db/repos/distros/profiles/CLD/amd64/20. Each profile is layered over its parents, and the final result is the sum of all profiles in the chain: the CLD profile sits on top of the Calculate desktop profile calculate:default/amd64/20/desktop, which in turn sits on top of the Gentoo profile gentoo:default/linux/amd64/23.0/split-usr.

To see the full set of active flags, run:

The variable already contains quite a few keywords. Do not edit the profile's make.defaults files directly: these changes will be reverted when the repository is updated.

To change the default values, add the keywords you need to the USE variable, or remove the ones you do not by putting a minus in front of the word. Global edits in Calculate are kept in the file /etc/portage/make.conf/custom (for the make.conf directory, see the page Configuring your system with variables). For example, to drop KDE and Qt support and add LDAP, append a line to this file; the line below is a sample setting for a global flag, not the actual contents of the file:

USE="-kde -qt5 ldap"

The same settings can also be deployed automatically with templates - this is how, for example, the distribution provides the address of the binary package repository; for details, see the Templates page.

USE flags for individual packages

Sometimes a flag is needed by one or several applications rather than by the whole system. Such assignments go in the /etc/portage/package.use directory: a line of the file is a package name followed by its flags, and the file name can be any convenient one. In a clean Calculate installation the directory already contains a placeholder file custom with the comment "This file will be carried over during system installation": you can write to it or create your own files.

For example, only the VLC media player needs Blu-ray support. Create the file /etc/portage/package.use/vlc with a single line:

media-video/vlc bluray

or append that line with a single command:

You can also disable a flag explicitly for a single package while keeping it for the rest - for example, drop bzip2 support in PHP when it is enabled globally:

dev-lang/php -bzip2

Temporary USE flags

When you need a flag just once, do not edit the file twice: pass USE as an environment variable. The setting applies only to the command you enter; when the application is reinstalled or updated, whether explicitly or as part of a system update, the changes made by the temporary flag are lost.

Example: installing SeaMonkey without pulseaudio support:

Priority of values

USE settings are applied in order of increasing priority:

1. the default value from the make.defaults files of your profile;
2. the USE variable set by the user in /etc/portage/make.conf (in Calculate, the custom file of that directory);
3. lines in the files of the /etc/portage/package.use/ directory;
4. the USE variable passed in the command environment.

To see the resulting USE value the way Portage sees it, run:

The command prints all significant variables with their current definitions.

Bringing the system in line with the new flags

After you change USE flags, you need to bring the system in line with the new values. To do this, run emerge with the --newuse option:

Then run depclean to remove conditional dependencies that were installed with the "old" set of flags and have become unnecessary with the new one.

After depclean, emerge may suggest rebuilding applications that are dynamically linked against libraries of the packages slated for removal. Portage keeps the needed libraries until that rebuild is done, and stores the list of pending packages in the preserved-rebuild set. To rebuild, run:

Once all the steps are done, the system uses the new USE flag values.

A note on binary packages. In Calculate, --binpkg-respect-use=y is among the default emerge options: a ready-made binary package is used only when the set of USE flags it was built with matches the current settings; if they do not match, the package is built from sources. You do not need to change anything specifically for this.

Routine system updates in Calculate are run with the cl-update command: it synchronizes the repositories, updates world, applies templates and protects configurations.

Flags for individual packages

Viewing available USE flags

The exact wording of emerge messages is illustrative and may differ on your system. To see which USE flags a specific package takes into account, run emerge with the -p (or --pretend) and -v (or --verbose) options - the example below uses app-editors/nano:

These are the packages that would be merged, in order:

Calculating dependencies ... done!
Dependency resolution took 2.39 s (backtrack: 0/20).

[binary  N g   ] app-editors/nano-9.2::gentoo  USE="ncurses nls (unicode) -debug -justify -magic -minimal -spell -verify-sig" 694 KiB

Total: 1 package (1 new, 1 binary), Size of downloads: 694 KiB

The USE= line lists all the flags of the package with their current values: a word without a prefix is an enabled flag, one with a minus is disabled. The [binary N g] marker means that the package will be taken from the binary package repository; N is a new installation, g is the gentoo repository.

Besides emerge, the equery utility from the app-portage/gentoolkit package (installed in Calculate) shows which flags a package has active:

Replace [HTML_REMOVED] with the name of the package you need: equery prints only the list of flags, without descriptions. Flag descriptions come from the euse utility, part of the same gentoolkit package: euse -i <flag> shows the description of a flag taken from the profile summary files - use.desc for global flags and use.local.desc for local ones. You can also use it to enable and disable a flag for a single package.

REQUIRED_USE conditions

To work correctly, some ebuilds require or forbid certain combinations of USE flags. The requirements are written as a set of conditions in the REQUIRED_USE variable of the ebuild; the basics of working with ebuild are on the Working with ebuild page. The conditions guarantee that the features and dependencies are complete, so that the build succeeds and the program works as expected; if they are not met, emerge warns you and asks you to fix the settings.

Conditions take the following form:

• REQUIRED_USE="|| ( foo bar baz )" - at least one of foo, bar or baz (you may enable several);
• REQUIRED_USE="^^ ( foo bar baz )" - exactly one of foo, bar or baz;
• REQUIRED_USE="?? ( foo bar baz )" - no more than one of foo, bar or baz (EAPI 5 and later);
• REQUIRED_USE="foo? ( bar )" - if foo is enabled, bar must be enabled too;
• REQUIRED_USE="foo? ( !bar )" - if foo is enabled, bar must not be enabled;
• REQUIRED_USE="foo? ( || ( bar baz ) )" - if foo is enabled, at least one of bar and baz must be enabled.

If enabling the flag you need requires unmasking a package or extra keywords, emerge suggests the missing lines: in Calculate the --autounmask option is included in the default emerge options (for details, see the Portage features page).

See also

• Introduction to Portage - the basics of working with emerge.
• Configuring your system with variables - the make.conf directory and user files.
• Portage features - binary packages and --autounmask.
• Additional Portage functionality - equery, euse and other utilities.