Topgrade¶

ID: topgrade
Home page: https://github.com/topgrade-rs/topgrade
Version requirement: >= 17
Platforms: 🅱️ BSD · 🐧 Linux · 🍎 macOS · 🪟 Windows
Operations: upgrade_all
purl types: pkg:topgrade
CLI name: topgrade
Issues and PRs: 📦 manager: topgrade
Source: meta_package_manager/managers/topgrade.toml

A meta-meta-package-manager: topgrade wrapped by mpm.

topgrade is a Rust utility that auto-detects every package manager, runtime version manager, plugin manager and OS updater installed on the host, then runs each one in sequence. From mpm’s vantage point it looks like a black-box upgrader: there is no notion of installed packages, no concept of outdated entries, no search index, no install or remove primitives. Only upgrade --all makes sense, and it is the only operation declared here.

Adding topgrade to mpm’s pool is a knowing nod to XKCD #927 (https://xkcd.com/927/): for the system package managers both reach, routing through topgrade is structurally redundant. Everything else is the point. topgrade drives far more tools than mpm wraps, so it serves as the pool’s deliberate sinkhole: every runtime, plugin and OS updater too thin to earn a manager of its own stays reachable in the same mpm upgrade --all invocation (rustup, oh-my-zsh, JetBrains plugins, vim/tmux plugin managers, and so on) without mpm having to learn each one.

That is what lets a candidate whose entire surface is an upgrade be declined rather than wrapped: it reaches nothing mpm cannot already reach through here. A candidate offering an inventory, or any per-package verb, clears that floor, because topgrade offers neither for anything it drives. The vetting order is spelled out in docs/add-new-manager.md.

Caution: mpm upgrade --topgrade runs topgrade --yes to skip the interactive prompts. If you also select other managers that topgrade itself drives (brew, apt, pacman, …), those will be upgraded twice in the same run.

What `mpm` adds to `topgrade`¶

mpm reaches across every manager at once, not topgrade alone: mpm installed and mpm outdated cover topgrade 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.

Operations¶

Operation	Supported
`installed`
`outdated`
`orphans`
`search`
`install`
`upgrade`
`upgrade_all`	✓
`remove`
`sync`
`cleanup`
`doctor`

Selecting and configuring `topgrade`¶

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

[mpm]
topgrade = false

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

[mpm.managers.topgrade]
timeout = 900

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

Recipes¶

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

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

Privilege escalation¶

Topgrade runs sudo from inside its own commands: mpm never wraps it, keeps an already-warm credential cache alive for those internal escalations, and warns when a mutating call goes silent on a terminal with a cold cache, since a password prompt may be hiding in the stream.

See privilege escalation for the full policy.

Cooldown¶

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

Status: ➖ N/A (meta-upgrader; delegates to each underlying manager)

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: No registry of their own
Retraction: ➖ Not applicable: these managers either delegate to whichever manager they front (pkcon, topgrade) or wrap a retired project or a discontinued platform

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:

$ topgrade --version
topgrade 17.4.0

and extracted with:

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

Changelog¶

7.4.0 (2026-07-25)
- Marked as internal escalators (internal_sudo): pacstall re-execs itself through sudo pacstall and topgrade runs each privileged step through its own sudo, so mpm never wraps them, keeps a warm credential cache alive for their mid-run escalations, and watches for hidden password prompts.
6.5.0 (2026-05-25)
- Add topgrade itself as a supported manager; only upgrade --all is implemented (mpm upgrade --topgrade runs topgrade --yes). Requires topgrade >= 17.0.0. Beware running a manager twice if both are selected.