Binary Package Support in Gentoo: binpkg and getbinpkg

Portage is source-based by default, but it has had binary package support since early on. Two mechanisms cover this: producing binary packages from local builds (buildpkg, quickpkg), and consuming binary packages from a remote binary host (getbinpkg, binrepos.conf). Since late 2023, Gentoo also runs an official public binhost serving prebuilt packages for amd64 and arm64, which changes binary packages from a niche optimization into a default install path for most desktop use cases.

Package formats: XPAK/tbz2 vs GPKG

Older Portage versions produced binary packages as .tbz2 files — a tarball of the installed files with an XPAK metadata block appended to the end. This format has no native support for GPG signatures, extended attributes, or ACLs, and signature verification had to be bolted on separately.

Current Portage defaults to the GPKG format (.gpkg.tar), which is a proper tar container holding the data payload, metadata, and an optional detached GPG signature as siblings inside the archive. This is what makes binpkg-signing and binpkg-request-signature possible without external tooling.

/etc/portage/make.conf

# Explicitly pin the binary package format (gpkg is default on current Portage)
BINPKG_FORMAT="gpkg"

Note

Mixed environments are fine. Portage will read both formats on install; verification is only enforced per-package when a signature is actually present, unless binpkg-request-signature forces the issue.

Core FEATURES and emerge switches

Binary package behavior is controlled by a combination of FEATURES in make.conf and per-invocation emerge flags. The flags take precedence for a single run; the FEATURES entries make the behavior persistent.

Flag / Feature	Short	Effect
`--buildpkg`	`-b`	Build a binary package after compiling from source, in addition to installing normally.
`FEATURES="buildpkg"`	—	Same as `-b`, applied to every merge.
`--usepkg`	`-k`	Use an existing binary package if one satisfies the requested version/USE combination; otherwise fall back to source.
`--usepkgonly`	`-K`	Only install from binary packages. Fails the merge if no matching binpkg exists — never compiles.
`--getbinpkg`	`-g`	Allow fetching binary packages from a configured remote binhost, not just `PKGDIR`.
`--getbinpkgonly`	`-G`	Like `-K` but restricted to remote binhost packages, ignoring local `PKGDIR` contents.
`FEATURES="getbinpkg"`	—	Always allow remote binhost fetches without passing `-g` each time.

A common workstation setup pulls prebuilt packages when they match, and compiles when they don't:

$ emerge --ask --update --deep --newuse --with-bdeps=y --getbinpkg --usepkg @world

And an unattended build host that produces binaries for other machines to consume:

/etc/portage/make.conf

FEATURES="buildpkg"
PKGDIR="/var/cache/binpkgs"

Local binary packages: PKGDIR and quickpkg

Locally produced binary packages live under PKGDIR, which defaults to /var/cache/binpkgs. This directory is structured by category, and Portage maintains a Packages index file at its root describing every binpkg it contains — the same index format used by remote binhosts.

If a package is already installed and you want a binary package for it without rebuilding, use quickpkg:

$ quickpkg --include-config=y sys-apps/portage

Tip

This is the fastest way to get a fleet-ready binhost off a single already-built machine: install and configure normally, then run quickpkg across the world set instead of rebuilding with -b.

To regenerate the Packages index after manually dropping files into PKGDIR, or after removing stale entries:

$ emaint binhost --fix

Consuming a remote binhost: binrepos.conf

The legacy way to point Portage at a remote binhost was the PORTAGE_BINHOST variable in make.conf. That variable is now deprecated in favor of /etc/portage/binrepos.conf, which supports multiple named repositories with independent priorities and per-repository signature policy.

/etc/portage/binrepos.conf/gentoo.conf

[gentoo]
priority = 9999
sync-uri = https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64/
verify-signature = true

sync-uri must point at the directory containing that repository's Packages index, not at an individual package. When more than one repository is configured, Portage resolves conflicts by priority — the higher-priority source wins for a given package/version. Most Gentoo stage3 tarballs already ship a binrepos.conf pointed at the matching stage's own binhost.

Warn

Multi-repo resolution is version-based, not USE-based. If two configured hosts both serve the same package version built with different USE flags, Portage only considers the first one found — it will not search further for a USE match. Keep binhosts USE-compatible with the local profile if running more than one.

The official Gentoo binhost

Gentoo has run a public binhost since late 2023, covering common packages for amd64 and arm64 across a range of USE flag combinations and CPU optimization levels. It is intended to make -k/-g the default path for desktop-class installs rather than an advanced-user optimization.

Minimal setup on a stage3 that doesn't already have it configured:

$ mkdir -p /etc/portage/binrepos.conf
$ getuto

getuto is the Gentoo Trust Tool — it provisions the GPG keyring used to verify packages signed by Gentoo Release Engineering, at /etc/portage/gnupg. With binpkg-request-signature enabled, getuto is invoked automatically before every fetch to pick up key rotations and revocations.

/etc/portage/make.conf

FEATURES="getbinpkg binpkg-request-signature"

$ emerge --ask --getbinpkg --usepkg firefox

Package integrity and signing

Three separate toggles govern signing behavior, and it's worth keeping them distinct:

Setting	Applies to	Behavior
`FEATURES="binpkg-signing"`	Producer	Sign binary packages as they are built locally.
`verify-signature` in `binrepos.conf`	Consumer, per-repo	Require a valid signature for packages from that specific repository.
`FEATURES="binpkg-request-signature"`	Consumer, global	Reject any unsigned package from any source. Overrides per-repo settings; does not support mixing signed and unsigned sources.

Signing requires a private key in the signing keyring (default /root/.gnupg) and a matching trusted public key in the verification keyring (/etc/portage/gnupg). To sign packages that already exist on disk without rebuilding:

$ gpkg-sign /var/cache/binpkgs/sys-apps/portage-3.0.76-1.gpkg.tar

Danger

Setting verify-signature = false for a custom binhost disables integrity checking entirely for that source — Portage will install whatever it fetches without validating it came from the expected builder. Only do this for a binhost you control end-to-end (build host and client on a trusted network), and prefer signing the packages instead.

Cleanup and maintenance

PKGDIR is not self-pruning — every binary package built with buildpkg or produced with quickpkg accumulates until removed manually. app-portage/gentoolkit provides eclean-pkg for this:

# Remove binpkgs for versions no longer installed
$ eclean-pkg --deep

# Preview without deleting
$ eclean-pkg --deep --pretend

Recent gentoolkit releases support cleaning across multiple configured binpkg locations rather than only the primary PKGDIR, which matters once a machine has both a local build cache and a synced copy of a remote binhost.

For binhosts serving many clients, Portage can attach a time-to-live to the Packages index via PORTAGE_BINHOST_HEADER_TTL (seconds), letting clients cache the index rather than refetching it on every invocation.