MangoHud session-aware usage

Scope

MangoHud exposes Vulkan/OpenGL metrics, but the correct launch path depends on who owns the process and runtime. Metric availability depends on GPU, driver, sensors, permissions, and build options.

Session matrix

ContextSupported entry pointDo not assume
SteamOS Gaming Mode
Built-in performance overlay first
Desktop package controls Gaming Mode
Native desktop Steam
mangohud %command%
Flatpak layer is available
Nested Gamescope on desktop
gamescope --mangoapp -- %command%
Regular injection is supported
Flatpak Steam/application
Matching Vulkan layer plus scoped override
Host and sandbox runtimes match

Trust boundary

MangoHud injects an overlay and reads frame timing, process, driver, sensor, temperature, and power data when available. Logs may expose game paths, hardware, usernames in paths, and timestamps. Upstream's public upload service publishes uploaded logs.

Supported installation

In Gaming Mode, use SteamOS's built-in overlay. On a normal desktop, use the distribution package or upstream release. For Flatpak, first identify the application's runtime and install the matching MangoHud Vulkan layer; do not guess a branch.

Use these launch forms only in their matching context:

Verification

Confirm the expected overlay appears, metric values change under load, and the game still uses the intended runtime. Compare overlay readings with a fixed benchmark scene; missing sensor fields are not automatically a game-performance fault.

Update

Update MangoHud through the same package or Flatpak-runtime channel used to install it. Recheck Gamescope compatibility and Flatpak runtime branches after major platform updates.

Uninstall

Remove per-game launch options first. For the explicit environment override shown by upstream, remove only the MangoHud variable so unrelated application permissions remain intact:

Rollback

Restore the original launch option, overlay level, configuration file, and logging state. Keep local logs only as long as needed and remove unintended public uploads through the current service workflow.

Recommended use

Use MangoHud for a controlled benchmark or desktop session needing metrics not exposed by the SteamOS overlay. Prefer the built-in overlay for routine Gaming Mode checks.

Frequently asked questions

Should I use mangohud directly inside Gamescope?
Should I use mangohud directly inside Gamescope?
No. Upstream says ordinary MangoHud with Gamescope is unsupported and documents Gamescope's --mangoapp path instead.
Does removing an overlay delete benchmark logs?
Does removing an overlay delete benchmark logs?
Not necessarily. Remove the launch option or override first, then inventory local logs separately. Publicly uploaded logs require the upload service's deletion process.

Sources

Version history

  • 2026-07-15: Phase 6 native, Gamescope, Flatpak, privacy, and rollback review.