Gentoo emerge¶

ID: emerge
Links: Home page · Documentation · Repository · Wikipedia
Upstream stars: ⭐ 671
Last commit: 2026-09-26
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: emerge.py

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

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

The outdated listing and the whole-system upgrade operate against the @world set.

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 %^(htop	tmux)$`
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`	✅	Reads through the companion `qlist` tool, expected on the `PATH`.
`outdated`	✅
`orphans`	✅
`search`	✅
`install`	✅
`upgrade`	✅
`upgrade_all`	✅
`remove`	✅
`sync`	✅
`cleanup`	✅	Trims distfiles through the companion `eclean` tool, after a full `@world` upgrade that makes `--depclean` safe. The `--orphans` flag runs the system-wide orphan sweep.
`doctor`

Configuration¶

Ignore emerge on the mpm CLI by passing the --no-emerge option.
Ignore it for every run in your configuration:
```
[mpm]
emerge = false
```
Raise the timeout of all emerge calls:
```
[mpm.overrides.emerge]
timeout = 900
```

Run mpm config-template emerge to print all overridable settings for your configuration file:

[mpm.overrides.emerge]
cli_names = [
    "emerge",
]
cli_search_path = []
dry_run = false
ignore_auto_updates = true
plan = false
post_args = []
pre_args = [
    "--quiet",
    "--color",
    "n",
    "--nospinner",
]
pre_cmds = []
requirement = ">=3.0.0"
stop_on_error = false
unmaintained = false
version_cli_options = [
    "--version",
]
version_regexes = [
    "Portage\\s+(?P<version>\\S+)",
]

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.

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.

Its privileged operations are cleanup, install, remove, sync, upgrade, upgrade_all.

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); --cooldown best-effort opts back in.

Reference traces¶

A collection of raw native outputs captured from the manager’s own CLI and recorded in the manager source. 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
app-admin/sudo-1.9.17_p2
app-alternatives/awk-4
app-arch/unzip-6.0_p29-r2
app-misc/pax-utils-1.3.10
app-misc/tmux-3.5a
app-shells/bash-5.3_p15
dev-perl/Locale-gettext-1.70.0_p20181130
dev-perl/SGMLSpm-1.1-r2

$ emerge --color n --nospinner --update --deep --pretend --columns @world
[ebuild     U  ] sys-process/htop                                      [3.5.3]                      [3.5.1]
[binary    gU  ] app-editors/nano                                      [9.2-1]                      [9.1]

$ emerge --quiet --color n --nospinner --depclean --pretend
app-misc/tmux: 3.5a none none
dev-libs/libevent: 2.1.13 none none

All selected packages: =app-misc/tmux-3.5a =dev-libs/libevent-2.1.13
Packages installed:   327
Packages in world:    8
Packages in system:   50
Required packages:    325
Number to remove:     2

Version check¶

The version is probed by running:

$ emerge --version
Portage 3.0.81.3 (python 3.14.7-final-0, default/linux/arm64/23.0, gcc-15, glibc-2.43-r2, 6.18.48-gentoo-dist-bin aarch64)

and extracted with:

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

Upstream project¶

Metrics	`gentoo/portage`
Activity
Popularity
Metadata

Changelog¶

8.0.0 (2026-09-20)
- Fix outdated and search, which reported nothing on Gentoo: the global --quiet they sent strips the fields their parsers read.
- Correct the commands shown on each manager’s page, which named fewer options than mpm actually runs.
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.