Gentoo Binary Host Quickstart

From Gentoo Wiki
(Redirected from Binary package quickstart)
Jump to:navigation Jump to:search

Gentoo systematically provides binary packages through the Gentoo binary package host (aka Gentoo binhost), using mirrors hosted by the Gentoo project. Binary packages from the Gentoo binhost can make installation and updates easier and quicker, especially on less performant hardware.

For many years Portage has included support for binary packages, and a few binary "-bin" packages have been provided in the Gentoo ebuild repository. With the new Gentoo binary package host, binary package availability has been widened even more, and installing and updating software on Gentoo is now quicker and easier than ever! See the news item for more information.

For amd64 (x86-64) and arm64 (aarch64), the Gentoo binhost includes many packages used on desktop systems, from KDE Plasma to Gnome and from LibreOffice to TeXLive, and these binary packages are updated daily. For other architectures and system types, the package directories contain just the core packages, and the binary packages for these arches are updated approximately once a week.

There are advantages to using the pre-built binary packages, though building packages locally from source also has value for some cases. For a given system, the choice between binary or source-based packages might depend on things like the specific use-case, and user-preference. Gentoo aims to provide users with the choice to use the distribution in the way that suits them best (see here for further information), so Portage can default to binary packages, and fall back on source-builds when requested or required.

This article describes using the fully-supported Gentoo binary package host for amd64 and arm64 with the settings the packages are compiled with. Further documentation shows what is supported on other architectures and profiles.

See also
The binary package guide has more general information on binary packages and binary package hosts on Gentoo. The binhost project page has information about the development of the Gentoo binhost.

Advantages of using the Gentoo binhost and what isn't available with it

There are several key benefits to using the Gentoo binary package host:

  • Ease and speed of getting a full installation up and running from scratch
  • Fast package installation and upgrades
  • Storage or RAM availability is no longer an issue when installing larger packages (i.e., some packages need X GB of RAM for their compilation)
  • Older systems can be set up rapidly and maintained without waiting longer than needed for packages to build (compile)
  • Fast updates and fast set-up time for cloud instances

The main downside of using binary packages from the Gentoo binhost, over compiling locally, is that -march=native or similar optimizations are not available, which can reportedly give up to a 5% boost on x86-64 processors for some cases. Of course if these optimizations are required, packages can always be built locally, even when mixing binary packages into the installation.

The Gentoo binhost can only provide binary packages if the locally-requested USE flag combination is not changed from the default setting(s) used for the creation of the binary packages. If the user requests non-default USE flags for a package, then the package will need to be compiled locally. Portage can automatically either install from a binary package by default, or build a package locally when needed.



Files in the directory /etc/portage/binrepos.conf tell Portage where to find binary packages. New Stage3 files already come with a suitable binrepos.conf configuration; in existing installations it will need to be added.

Using a local Gentoo mirror is highly recommend to reduce server load and to speed up downloads on the local end:

FILE /etc/portage/binrepos.conf/gentoobinhost.confUK Mirror Example, amd64
priority = 9999
sync-uri =
FILE /etc/portage/binrepos.conf/gentoobinhost.confCN Mirror Example, arm64
priority = 9999
sync-uri =

The sync-uri in binrepos.conf contains at its end the local system architecture and type of installation. The examples above are given for normal amd64 or arm64 installations.

When using a hardened, musl, llvm profile, x32, or even an entirely different architecture, these paths are not correct. Corresponding directories exist, but have only the package set found within the stage3.

Package signature verification

Now, enable the binpkg-request-signature Portage feature to require verification of GPG signatures:

FILE /etc/portage/make.conf
FEATURES="${FEATURES} binpkg-request-signature"

Once binary packages have to be downloaded, emerge will automatically run the Gentoo Trust Tool known as getuto to set up a ring of GPG keys that are trusted for binary package installation.


In the past, /etc/portage/gnupg may have been used for older methods of verifying the Gentoo repository. If it exists, getuto won't override it, but the correct settings may be missing. If hitting issues, move away the old directory, then run getuto again:

root #mv /etc/portage/gnupg /etc/portage/gnupg.bak ; getuto


Below are some useful settings that can be applied via EMERGE_DEFAULT_OPTS in make.conf or on the emerge command line to improve the experience of working with Gentoo binary packages.

--getbinpkg (-g)

Adding --getbinpkg will automatically download and use a binary package when a suitable one is available on the servers. If no suitable binary package can be found, the package will be compiled from source as usual.

--usepkgonly (-K)

Using --usepkgonly will tell Portage to only use binary packages and exit if no suitable one can be found locally or (with -g) for download.


This can be set to y(es) or n(o) and controls whether build dependencies of packages are downloaded and/or installed. For binary package installation, it defaults to no. For source-based installation, the build dependencies are required and are accordingly also installed.


Do not set --binpkg-respect-use=n lightly, in EMERGE_DEFAULT_OPTS or otherwise. It will break the system.

This, set to y(es) (the default), tells Portage to accept binary packages only if use flags match the precise requirements and compile the package from source otherwise. Set to n(o), the differences between a user's configuration and the configuration used to make the binary package are ignored, and the binary package is installed anyway. Warning: Dangerous.

Emerging packages

When emerging packages, add a single switch to the emerge command line: --getbinpkg (-g).

Single package

To install a single package using the binhost use the command below:

root #emerge --ask --verbose --getbinpkg app-editors/nano

or the shorthand:

root #emerge -avg app-editors/nano

System update

To perform a full system update using the binhost use:

root #emerge --ask --verbose --update --deep --changed-use --getbinpkg @world

or shorthand:

root #emerge -avuDUg @world

Package settings

amd64, amd64/17.1/x86-64


The packages are built with CFLAGS="-O2 -pipe -march=x86-64 -mtune=generic", which means all x86-64 CPUs are supported.


This binhost is built with USE flags of the following profiles:

  • default/linux/amd64/17.1/no-multilib
  • default/linux/amd64/17.1/desktop/gnome/systemd
  • default/linux/amd64/17.1/desktop/plasma/systemd

This will cover most of the USE flag combinations needed for both a OpenRC and systemd system.

arm64, arm64/17.0


The packages are built with CFLAGS="-O2 -pipe", which means all arm64 CPUs are supported.


This binhost is built with USE flags of the following profiles:

  • default/linux/arm64/17.0
  • default/linux/arm64/17.0/desktop/gnome/systemd
  • default/linux/arm64/17.0/desktop/plasma/systemd

This will cover most of the USE flag combinations needed for both a OpenRC and systemd system.

Other arches and experimental profiles on amd64 and arm64

Only the packages offered in a stage3 are provided here like sys-devel/gcc and sys-app/shadow as two examples. These are also updated weekly rather than daily


The packages are built with CFLAGS="-O2 -pipe", which means all CPUs are supported in their respect profile architects.


Listing a few examples of how this would work for a user's system.

amd64 using llvm as system compiler:

  • default/linux/amd64/17.0/clang

arm64 using musl as the libc:

  • default/linux/arm64/17.0/musl

ppc using the standard profile:

  • default/linux/ppc/17.0

m68k using systemd:

  • default/linux/m68k/17.1/systemd

USE flags will be the defaults set by the profile itself.

Frequently asked questions

Various questions are covered in the Gentoo news Gentoo goes Binary!.

Review the frequently asked questions before asking for help when using the Gentoo binhost.

Update GCC first

When using the binhost always use the latest stable version of GCC to avoid errors like /usr/libexec/gcc/x86_64-pc-linux-gnu/ld: /usr/lib/gcc/x86_64-pc-linux-gnu/12/../../../../lib64/ undefined reference to `std::ios_base_library_init()@GLIBCXX_3.4.32

Portage still tries to compile from source

If there is a binary package available on a binhost but Portage is not using it, it may well be because of a mismatch between the USE flags that were requested to install the package with, and the USE flags that were applied to build the binary package.

The USE flags that were used to build the available binary package may be listed by using the following command:

user $emerge --pretend --usepkgonly --binpkg-respect-use=n <package-X>

To allow Portage to install from the available binary package, adjust the requested USE flags accordingly, in /etc/portage/make.conf or /etc/portage/package.use.

See also