Gentoo emerge¶

ID: emerge
Home page: https://wiki.gentoo.org/wiki/Portage#emerge
Version requirement: >= 3
Platforms: 🅱️ BSD · 🐧 Linux · ⨂ Unix
Operations: installed · outdated · orphans · search · install · upgrade · upgrade_all · remove · sync · cleanup
purl types: pkg:ebuild · pkg:emerge
CLI name: emerge
Every call: emerge --quiet --color n --nospinner <command>
Issues and PRs: 📦 manager: emerge
Source: meta_package_manager/managers/emerge.py

Portage’s emerge, Gentoo’s source-based package manager.

Documentation: emerge(1) man page.

Command equivalences with other managers are listed in Pacman/Rosetta.

The outdated listing and the whole-system upgrade operate against the @world set. The progress spinner and ANSI coloring are disabled on every call, leaving output the regexes can parse.

Note

Two operations lean on companion Portage tools rather than emerge itself: installed reads the package list through qlist and cleanup trims distfiles through eclean. Neither is resolved through cli_path the way the reference emerge binary is; both are expected on the PATH.

Warning

cleanup forces a full @world upgrade before running --depclean: Portage refuses to remove packages until every dependency is resolved, so depcleaning a partially-upgraded system could drop still-needed packages.

What `mpm` adds to `emerge`¶

mpm reaches across every manager at once, not emerge alone: mpm installed and mpm outdated cover emerge alongside every other manager you run in one table, mpm upgrade --all updates them together, and mpm sbom exports the whole machine as one bill of materials.

Every mpm command also gains --dry-run and --plan previews, cross-scheme version comparison and purl identifiers. See manager augmentations for how each one is built.

Your `emerge` commands, in `mpm`¶

You already know emerge: each operation maps one-to-one onto mpm, in an interface shared by every manager.

To…	With `emerge`	With `mpm`
List what’s installed	`qlist --installed --verbose --nocolor`	`mpm --emerge installed`
List outdated packages	`emerge --update --deep --pretend --columns @world`	`mpm --emerge outdated`
Search for a package	`emerge --search blah`	`mpm --emerge search blah`
Install a package	`sudo emerge dev-vcs/git`	`mpm install pkg:emerge/dev-vcs/git`
Upgrade one package	`sudo emerge --update dev-vcs/git`	`mpm --emerge upgrade dev-vcs/git`
Upgrade everything	`sudo emerge --update --newuse --deep @world`	`mpm --emerge upgrade --all`
Remove a package	`sudo emerge --unmerge dev-vcs/git`	`mpm remove pkg:emerge/dev-vcs/git`
List orphaned dependencies	`emerge --depclean --pretend`	`mpm --emerge orphans`
Clear caches	`sudo eclean distfiles`	`mpm --emerge cleanup --cache`

Prefix any command above with --dry-run to simulate the underlying manager calls without touching the system: the safe way to watch what mpm would do before trusting it.

Operations¶

Operation	Supported	Notes
`installed`	✓
`outdated`	✓
`orphans`	✓
`search`	✓
`install`	✓
`upgrade`	✓
`upgrade_all`	✓
`remove`	✓
`sync`	✓
`cleanup`	✓	`--orphans` runs the system-wide orphan sweep
`doctor`

Selecting and configuring `emerge`¶

Deselect emerge for a single run with --no-emerge, or persist the choice in your configuration:

[mpm]
emerge = false

The arguments and environment variables listed in the box atop this page are forced on every emerge call, so runs stay quiet, non-interactive and reproducible: the defaults you would set in CI anyway.

Keep it enabled but tune how mpm drives it with a per-manager override:

[mpm.managers.emerge]
timeout = 900

mpm config-template emerge prints every overridable attribute as a ready-to-paste block.

Recipes¶

A few jobs you would otherwise script around emerge, one mpm command each:

Snapshot and clone a machine: mpm --emerge dump emerge.toml, then mpm restore emerge.toml on the next one.
Export a compliance SBOM: mpm --emerge sbom (CycloneDX by default, --spdx for SPDX).

Privilege escalation¶

System-wide manager: mpm wraps its privileged operations in sudo out of the box. Instead of letting the tool prompt mid-run, mpm primes the credential cache up-front, with a single branded password prompt at most. Turn escalation off for rootless setups with --no-sudo or the per-manager sudo override.

See privilege escalation for the full policy.

Cooldown¶

State of Gentoo emerge’s release-age gating, from the cooldown support table:

Status: ❌ None

A cooldown only pays off where a compromised release can be withdrawn while the clock runs, and can only be emulated where the registry dates its releases. From the retraction table:

Registry: Source-based recipe trees
Retraction: Index revert of the recipe tree
Publish date: ❌ a recipe carries no publication date

With --cooldown set, mpm skips this manager’s install and upgrade operations rather than run them unguarded (fail-closed); --allow-unsupported-managers opts back in.

Version probe¶

The version is probed by running:

$ emerge --version
Portage 3.0.30 (python 3.9.9-final-0, gcc-11.2.1, 5.15.32-gentoo-r1 x86_64)

and extracted with:

r"Portage\s+(?P<version>\S+)"

Reference traces¶

Raw native outputs captured in the manager source: the reference mpm’s parsers were written against. If you know Gentoo emerge well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ qlist --installed --verbose --nocolor
acct-group/audio-0-r1
acct-group/cron-0
app-admin/hddtemp-0.3_beta15-r29
app-admin/perl-cleaner-2.30
app-admin/system-config-printer-1.5.16-r1
app-arch/p7zip-16.02-r8

$ emerge --update --deep --pretend --columns --color n --nospinner @world
[blocks  B     ] app-text/dos2unix
[ebuild   N    ] app-games/qstat   [25c]
[ebuild    R   ] sys-apps/sed      [2.4.7-r6]
[ebuild       U] net-fs/samba      [2.2.8_pre1]      [2.2.7a]
[ebuild       U] sys-devel/distcc  [2.16]            [2.13-r1] USE=ip6* -gtk
[ebuild r     U] dev-libs/icu      [50.1.1:0/50.1.1] [50.1-r2:0/50.1]
[ebuild r  R   ] dev-libs/libxml2  [2.9.0-r1:2]       USE=icu

$ emerge --quiet --color n --nospinner --depclean --pretend
Calculating dependencies... done!
>>> These are the packages that would be unmerged:

 dev-libs/libpcre
    selected: 8.45-r1
   protected: none
     omitted: none

 app-misc/tmux
    selected: 3.3a
   protected: none
     omitted: none

All selected packages: =dev-libs/libpcre-8.45-r1 =app-misc/tmux-3.3a

>>> 'Selected' packages are slated for removal.
>>> 'Protected' and 'omitted' packages will not be removed.

Feed any of these through mpm and the raw output becomes one uniform table, the same shape for every manager: filter it, project columns, or export it (mpm --emerge installed --output json, or csv, toml, yaml), each package carrying a purl and a version comparable across managers.

Changelog¶

7.4.0 (2026-07-25)
- Plain cleanup no longer removes orphaned packages: their native sweeps moved behind cleanup --orphans. This also stops emerge’s cleanup from triggering its pre-depclean world upgrade unless --orphans is given.
- The cleanup steps split into cleanup_orphan (the safety upgrade plus --depclean) and cleanup_cache (eclean distfiles), giving emerge native cleanup --orphans support.
6.4.0 (2026-04-27)
- Add remove operation. Closes #1775.
6.2.0 (2026-03-25)
- Add --quiet, --color n and --nospinner to pre_args. Refactor inline flags.
5.5.0 (2022-07-08)
- Locate and validate qlist and eclean CLI availability.
5.0.0 (2022-04-25)
- Add emerge support.