Profile (Portage)

A Portage profile Article description::specifies the default state of [[USE flags, sets default values for most variables found in, defines a set of system packages, and selects available package versions.]]

Profiles are central to a Gentoo system because they define core system functionality. New profiles are made available when there are fundamental changes to the way Gentoo works. Profile releases can be years apart, the current (now being 2022) profile is 4 years old (17.1).

A profile is selected at install time, according to the intended use of the system, and is usually only changed if absolutely necessary, or when a new profile is released.

Profiles are defined on an ebuild repository basis; the ones from the main repository are maintained by the Gentoo developers, but users can define their own.

The  module of the eselect tool allows users to switch profiles.

What is a profile
A profile is a set of configuration files, stored locally in a subdirectory of, that describe things such as the ebuilds that are considered system packages, the default USE flags, and the architecture on which the system is running.

Profiles set or unset USE flags (globally or per-package), can force USE flags to be unconditionally set or unset (globally, for the architecture's stable branch, or per package), and can mask packages or specific versions of them. Profile structure and function is specified by the Package Manager Specification (PMS).

The profile in use is determined by the symbolic link, which points to a subdirectory of that holds the profile files. For instance, the default 17.1 profile can be found at. The files in the parent directories are part of the profile as well (and are therefore shared by different subprofiles). This is why profiles are said to be cascaded. Profiles are set with the eselect profile tool, though this can be done manually.

Profiles obsoleted by new ones are kept in along with the current ones, but they are marked as deprecated. When that happens a file named is put in the profile directory. The content of this file is the name of the profile that should be "upgraded to"; Portage uses this information to automatically warn administrators when they should update to a new profile.

There are various reasons that a new profile may be created: the release of new versions of core packages (such as, , or ) that are incompatible with previous versions, a change in the default USE flags or in the virtual mappings, or maybe a change in system-wide settings.

Changing profile
Profile changes can be non trivial. Changing to or from Hardened or SELinux profiles, for example, requires specific steps, as described in the relevant documentation.

Changing from OpenRC profiles to systemd profiles, or vice versa, must be done following the documentation.

If a profile is to be changed to a more recent version, see the next section for information on updating profiles.

See the Handbook for how to switch profiles. Read all relevant documentation before switching profiles. As always, systems should be regularly backed up, particularly before system changes.

Migrating to a new profile (updating, or upgrading profiles)
The user is informed of the availability of a profile update by the publication of a news item, which will be reported after a Gentoo ebuild repository sync. This will include detailed instructions that should be properly followed. A profile upgrade is a non trivial operation and, as always, systems should be regularly backed up - particularly before system changes.

See the article on upgrading Gentoo for information on profile updates.

Profile structure
Profiles are defined in directories contained in the subdirectory of an ebuild repository, which also contains the mandatory  file that specifies the name of the ebuild repository. These are some of the files that can be present in a directory that defines a profile:


 * , which specifies the EAPI to use when handling the directory in question.
 * , which specifies packages that are members of the system set.
 * , which specifies masked packages. The administrator can unmask a package masked by the profile using.
 * , with -like variable assignments, including USE flag global default state (set or unset) and profile variables with special meaning (like ARCH, USE_EXPAND , CONFIG_PROTECT , IUSE_IMPLICIT , etc.). Administrator settings in and  override profile settings in.
 * , which defines default USE flag state on a per package basis. Administrator settings in and  override profile settings in.
 * and, which unconditionally set or unset USE flags, overriding administrator settings in and . If a flag is both masked and forced, the mask takes precedence.
 * and, which unconditionally set or unset USE flags on a per package basis, overriding administrator settings in and , and profile settings in  and.
 * ,, and , which work like , ,  and , but override them for packages in the stable branch of the current architecture.

USE flag settings in profile and  files can be overridden by the administrator with files of the same name in directory. For complete information about profile directory structure please consult the PMS. A summary is also contained in the Devmanual and.

Combining profiles
Profile settings can be combined in a cascading/stacking fashion, by including a file named in the directory that defines the profile. This makes the profile inherit settings from other profiles, which can be partially overriden. For example, by unsetting a USE flag by default that is set by default in a parent profile and vice-versa, unforcing or inverting its forced state, unmasking packages masked in a parent profile, adding or removing additional packages to/from the system set, etc. must contain a list of profile pathnames, relative to the directory that contains the file. As an extension, with added to the  key in, Portage also allows prepending an installed ebuild repository name (as specified in ) followed by a colon (':') to a profile pathname, which is then interpreted relative to the  subdirectory of the named ebuild repository.

Because parent profiles can also contain a file, an inheritance tree is produced as a result. The Package Manager Specification specifies how settings in each file of a profile directory (i.e., , and , etc.) combine. In particular, it defines an ordering of parent profiles to determine the final settings: the inheritance tree is traversed depth-first, left-to-right, with multiple occurrences of the same profile processed repeatedly. The left-to-right order is defined by line order in files.

The PMS uniformly calls 'profile' all directories with suitable structure that are contained in an ebuild repository's subdirectory. A subset designated as 'valid for use' must be listed in file, a text file that must contain lines with three fields separated by whitespace characters (space and TAB):


 * The first one is an architecture, in the format valid as the value of ARCH (and for setting KEYWORDS in ebuilds), e.g., , , etc. These are listed in the main repository's file.
 * The second one is a profile path name, relative to the directory.
 * The third and last one is a 'stability indicator'. The Gentoo ebuild repository, for instance, uses stable, dev and exp (experimental) for that field.

The command only shows profiles in  files of all repositories configured in, with an architecture field that matches the machine's architecture. These are the ones that in most contexts are referred to as 'profiles' with no further qualification. Profiles not named in might be named in other profiles'  files, and can be thought of as 'subprofiles' or 'profile building blocks'.

Following is an example that shows parent profiles and the inheritance tree for profile from the Gentoo ebuild repository. Profiles pathnames relative to the subdirectory are shown so that the filesystem layout can be inferred, top-to-bottom ordering respects line ordering in relevant  files. default/linux/amd64/17.1/desktop/gnome/systemd 17 | L +--> default/linux/amd64/17.1/desktop/gnome 15 |    | L |    +--> default/linux/amd64/17.1/desktop 12 |    |     | L |    |     +--> default/linux/amd64/17.1 10 |    |     |     | L |    |     |     +--> default/linux/amd64 3 |    |     |     |     | L |    |     |     |     +--> base 1 |    |     |     |     | R |    |     |     |     +--> default/linux 2 |    |     |     |  |     |     |     +--> arch/amd64/lib32 7 |    |     |     |     |  |     |     |     |     +--> arch/amd64 6 |    |     |     |           | L |    |     |     |           +--> arch/base 4 |    |     |     |           | R |    |     |     |           +--> features/multilib 5 |    |     |     | R |    |     |     +--> releases/17.1  9 |    |     |           |  |     |     |           +--> releases 8 |    |     | R |    |     +--> targets/desktop 11 |    | R |    +--> targets/desktop/gnome 14 |          |  |           +--> targets/desktop 13 | R +--> targets/systemd 16

The L and R markers indicate the leftmost and rightmost branches in the corresponding tree representation, and the numbers represent the order in which profiles are considered for computing the final settings. Profiles with larger numbers override settings in profiles with smaller numbers. The following table gives a quick overview of notable settings for each of the intervening profiles, as well as the relevant files that implement them:

For information about the exact way in which settings in the different profile files combine please consult the PMS.

Creating custom profiles
Users can create specialized, custom profiles not available in the Gentoo ebuild repository, and put them in an ebuild repository. They can refer to profiles from the Gentoo ebuild repository in their file using the 'gentoo:' prefix, to avoid recreating all profile definitions, provided that the  key in  of the ebuild repository contains, as shown below.

Following is an example of a custom profile created locally in an ebuild repository named 'local'. The ebuild repository is assumed to be in (i.e. the default location for ), world-readable and owned by a non-root user. It is also assumed to contain a package that installs libraries:

Example 1: Combining multiple profiles from the Gentoo ebuild repository
A profile named will be created, which inherits settings from  and  in the main Gentoo ebuild repository.

First, create the directory in the ebuild repository's  subdirectory:

Then, create the file:

Finally, insert the newly created profile in the ebuild repository's file, giving it a   'stability indicator' for example:

Verify that lists the new profile:

Example 2: Adding custom USE flags by profile
A profile named will be created, which inherits settings from  in the Gentoo ebuild repository, and two local profiles:, which sets the   USE flag and unsets the   USE flag by default for the package, and , which does exactly the opposite, to illustrate final settings determination.

First, create the and  directories in the ebuild repository's  subdirectory:

Then, create the directory:

Finally, insert the newly created profile in the ebuild repository's file, giving it a   'stability indicator' for example:

Verify that lists the new profile:

Now it is possible to actually switch to the new profile using :

Check the result:

This shows that updated the  symbolic link. In the general case, it would be necessary to run a world rebuild to apply the new settings to all packages, but checking first to make sure that the desired changes are going into effect with :

However, for this example, knowing that the profile settings only affect and assuming that the previously chosen profile was, only that package's reinstallation will be done.

This shows that because profile comes last in file, its setting override those in profile , and the 32-bit version of the package's libraries is built.

Messages printed by the package's makefile (informational ones highlighted) show variables ARCH, CHOST_x86 , CFLAGS_x86 (which adds GCC's  option for 32-bit builds) and LDFLAGS , set by profile , are being inherited and are available in the ebuild's environment.

Now to see what happens if line order is changed in :

This shows that because it now comes last in file, settings in profile override those in profile , and, on a reinstallation, the 32-bit version of the package's libraries would be removed, and library  would be built:

External resources

 * News item, "Experimental amd64 17.1 profiles up for testing", December 26th, 2017. Retrieved on December 16th, 2018.
 * gentoo-dev mailing list thread "Developers, please start switching to 17.1 amd64 profiles", May 22nd, 2018.
 * gentoo-dev mailing list thread "amd64 17.1 profiles are now stable", May 19, 2019.
 * News item, "amd64 17.1 profiles are now stable", June 05, 2019. Retrieved on June 05, 2019.
 * profiles: Finally deprecate amd64 17.0 profiles
 * — (no-symlink-lib) - kill SYMLINK_LIB = support.
 * Gentoo Forums thread "New profiles 17.1".