If you have ever wanted to know exactly how hard your GPU is working in the middle of a boss fight, or whether that Proton layer is causing a CPU bottleneck, MangoHud is the answer. It operates as a Vulkan layer and OpenGL hook that injects a configurable overlay directly into your running game -- no alt-tabbing, no separate window. What you see is what your hardware is doing right now.

MangoHud is the same engine that powers the performance overlay built into SteamOS and the Steam Deck. That alone should tell you something about how well it is trusted in the Linux gaming ecosystem.

"The excellent and incredibly useful Linux performance overlay."

-- Liam Dawe, GamingOnLinux, MangoHud 0.8.2 Release Coverage (November 28, 2025)

What MangoHud Displays

Out of the box, MangoHud surfaces a compact block of metrics in the corner of your screen. The default view shows FPS, a frame time graph, and CPU and GPU load percentages. With configuration you can add or remove virtually any metric. The full list of supported metrics includes:

  • FPS -- current frames per second with optional frame time graph
  • CPU usage -- aggregate percentage and optionally per-core load, plus CPU type per core on hybrid architectures (Intel P/E cores, ARM core codenames)
  • GPU usage -- per-process since version 0.8, rather than the previous global read
  • CPU and GPU temperatures -- Intel discrete GPU temperature readings require Linux kernel 6.13 or above and are only available via the i915 driver; the xe driver does not yet expose temperature. Intel integrated GPUs have limited hwmon support on Intel's side and do not expose power usage data
  • RAM and VRAM usage -- both system memory and video memory, per-process on 0.8+
  • CPU power draw -- logged alongside GPU power
  • Frame time -- useful for spotting stutters even when average FPS looks stable
  • Network activity -- configurable with network_color
  • GPU and CPU efficiency -- gpu_efficiency shows frames per joule; cpu_efficiency shows the same for the CPU; flip_efficiency inverts to joules per frame for power-budget comparisons
  • GPU power limit -- display the GPU's current power cap with gpu_power_limit
  • Process VRAM -- proc_vram shows VRAM usage attributed to the running process rather than the global GPU total
  • DirectX API layer -- dx_api attempts to surface the underlying Direct3D API version when running through Proton (work in progress as of 0.8.2)
  • Display server -- shows whether the game is running under X11 or Wayland
  • RAM temperature -- ram_temp supports DDR5 modules using the spd5118 kernel driver
  • vkBasalt status -- shows whether vkBasalt post-processing is active
  • FEX emulator stats -- fex_stats displays developer metrics for the FEX-Emu x86/x64 emulation layer on ARM hardware, added in 0.8.1
  • Horizontal separator color -- horizontal_separator_color (added in 0.8.2) lets you set a custom hex color for the dividers in horizontal layout mode
  • FPS limit indicator and frame pacing metrics
  • CPU clock speed -- cpu_mhz displays current CPU frequency in MHz and is also captured in performance logs as of 0.8.2
  • ftrace events -- ftrace surfaces kernel trace events reported through the Linux ftrace subsystem
  • Process memory -- procmem, procmem_shared, and procmem_virt show resident, shared, and virtual memory usage attributed to the game process
  • Display resolution -- resolution shows the current rendering resolution in the overlay
  • Wireless device battery -- device_battery=gamepad,mouse displays battery level for connected wireless gamepads and mice
  • Custom CPU temperature sensor -- cpu_custom_temp_sensor lets you specify a hwmon sensor path manually if MangoHud does not detect the right one automatically, useful on systems with multiple thermal zones
Consider this

MangoHud can show you per-process VRAM, per-process GPU load, CPU power draw, and frame times all at once. If your game stutters but FPS looks fine, which metric would expose the problem -- and why would average FPS mislead you?

A game can report 60 FPS while delivering an inconsistent experience because FPS is an average -- it smooths over per-frame variation. If 59 frames render in 8ms each but one frame takes 52ms, the average is still 60 FPS, but the player perceives a visible hitch. Frame time graphs expose this immediately: a spike in the graph corresponds directly to a perceived stutter. This is why MangoHud's frametime=1 config option and the frame time graph are considered more diagnostic than raw FPS for troubleshooting perceived smoothness. The frame_timing=1 option renders a rolling graph in the overlay that updates each frame, giving you a visual EKG of your game's render consistency.

The same principle applies to benchmarking. Two driver versions might produce identical average FPS, but one might have 1% lows that are 30% worse. MangoHud's logging captures per-frame timestamps so you can compute 1% lows, 0.1% lows, and frame time variance from the CSV output -- metrics that FlightlessMango.com calculates automatically when you upload a log.

Version note

This guide reflects MangoHud 0.8.2, released November 28, 2025. It includes large-scale OpenGL fixes, Intel GPU support (i915 and xe drivers), per-process VRAM and GPU usage, improved Wayland keybind handling, new efficiency metrics, Panfrost and Qualcomm KGSL platform support, CPU MHz logging, horizontal_separator_color for horizontal layout styling, and the proc_vram metric. MangoHud 0.8.1 (March 2025) added fex_stats for FEX-Emu ARM emulation metrics, Panthor ARM GPU driver support (Mali-G710 and newer), ram_temp for DDR5 memory temperature via the spd5118 kernel driver, Elbrus CPU temperature support, and reworked fps_metrics accuracy. As of 0.8, DLSYM hooking for OpenGL is enabled by default -- no extra environment variable needed. Earlier versions behave somewhat differently, particularly around OpenGL stability and multi-GPU reporting.

Installation

MangoHud is in the official repositories of every major distribution. For full coverage -- 64-bit games and 32-bit games -- you should install both the native and 32-bit packages where your package manager offers them separately.

"Install mangohud and lib32-mangohud since many old games are 32-bit-only."

-- Arch Wiki: MangoHud
install by distro 
# Arch Linux (extra + multilib)
$ sudo pacman -S mangohud lib32-mangohud

# Debian / Ubuntu 21.10+ / Linux Mint / Pop!_OS
$ sudo apt install mangohud

# Fedora
$ sudo dnf install mangohud

# openSUSE (install both for 32-bit app support)
$ sudo zypper install mangohud mangohud-32bit

# Flatpak (Flathub) -- for Flatpak Steam or Heroic Games Launcher
$ flatpak install flathub org.freedesktop.Platform.VulkanLayer.MangoHud

# Solus
$ sudo eopkg install mangohud
Ubuntu 32-bit limitation

The 32-bit MangoHud package is not available on Ubuntu via apt. This means 32-bit games and some Proton titles may not load the overlay on Ubuntu. On Arch Linux, lib32-mangohud from multilib covers this. On openSUSE, install mangohud-32bit alongside the main package. Debian-based distributions other than Ubuntu may have better 32-bit package availability depending on the release.

Flatpak Steam requires the Flatpak build of MangoHud

If you are using the Flatpak version of Steam, you must install MangoHud as a Flatpak as well -- the system package is sandboxed out and will not inject. The correct package is org.freedesktop.Platform.VulkanLayer.MangoHud on Flathub. After installing, give Flatpak apps access to your config with flatpak override --user --filesystem=xdg-config/MangoHud:ro. You can then enable MangoHud globally for Steam Flatpak with flatpak override --user --env=MANGOHUD=1 com.valvesoftware.Steam. The older com.valvesoftware.Steam.Utility.MangoHud package is no longer in active development.

Why Flatpak sandboxing matters here

The reason the system MangoHud package cannot inject into Flatpak Steam is a deliberate security boundary. Flatpak runs applications inside a bubblewrap sandbox that restricts access to host files, device nodes, and environment variables -- including LD_PRELOAD. This is the same isolation model that prevents a compromised application from reading your home directory or accessing host services without explicit permission. When you run flatpak override --user --filesystem=xdg-config/MangoHud:ro, you are granting read-only access to a specific config directory rather than giving the application blanket filesystem access. The :ro suffix is important -- it ensures that the Flatpak can read your MangoHud config but cannot write to it, maintaining the principle of least privilege. Avoid using --filesystem=host or --filesystem=home overrides as a workaround, because those effectively disable Flatpak's sandbox protection for your entire home directory.

Arch AUR note

If you are on an Arch-based system and find that the overlay does not activate reliably with stable releases from the extra repository, try mangohud-git and lib32-mangohud-git from the AUR. These track upstream changes more closely and can resolve activation issues that appear in point releases.

Launching Games with MangoHud

There are several ways to attach MangoHud to a game depending on how you launch it.

~ Which launch method should I use?
How are you launching the game?
Launch Options: mangohud %command% -- works for both native and Proton games. For Vulkan-only, MANGOHUD=1 %command% also works.
First install the Flatpak MangoHud: flatpak install flathub org.freedesktop.Platform.VulkanLayer.MangoHud. Then grant config access: flatpak override --user --filesystem=xdg-config/MangoHud:ro. Use mangohud %command% in Steam Launch Options, or enable globally with flatpak override --user --env=MANGOHUD=1 com.valvesoftware.Steam. The system package will not work -- the Flatpak sandbox blocks it.
Use mangoapp, not mangohud: gamescope --mangoapp -- %command%. The standard MangoHud prefix does not work inside gamescope's compositor.
Open the game's system settings in Lutris, enable advanced options, and set Command Prefix to mangohud. Alternatively, add MANGOHUD=1 to the game's environment variables.
Open the game settings in Heroic and toggle the MangoHud checkbox (v2.17.2+). For older versions, add MANGOHUD=1 to environment variables.
Run mangohud /path/to/game-binary directly. For OpenGL games, DLSYM hooking is on by default since 0.8.

Steam Launch Options

Right-click any game in your Steam library, choose Properties, and add the following to the Launch Options field:

$ mangohud %command%

This works for both native Linux games and titles running through Proton. For Vulkan games you can also export MANGOHUD=1 in your shell profile as a global enable, but the launch option approach gives you per-game control.

OpenGL Games

As of MangoHud 0.8, DLSYM hooking for OpenGL is enabled by default. You no longer need to set MANGOHUD_DLSYM=1. If you run into a specific game where DLSYM causes problems -- crashes or failure to launch -- you can disable it explicitly:

$ MANGOHUD_DLSYM=0 mangohud %command%

Some native OpenGL games override LD_PRELOAD, which can still prevent MangoHud from injecting its hook even with DLSYM active. For those titles, you may need to edit the game's launch script to include the MangoHud library path in LD_PRELOAD directly.

Security context: LD_PRELOAD and library injection

MangoHud's injection mechanism -- hooking into a running process via LD_PRELOAD and DLSYM -- is the same technique cataloged in the MITRE ATT&CK framework as T1574.006: Hijack Execution Flow: Dynamic Linker Hijacking. In a threat context, adversaries use LD_PRELOAD to inject malicious libraries that intercept system calls, hide artifacts, and escalate privileges -- it is a well-documented rootkit technique used in real-world Linux malware including Symbiote and PUMAKIT. MangoHud uses the same mechanism for a legitimate purpose (overlaying performance metrics), but this is worth understanding because it means any tool that uses LD_PRELOAD has the same level of access to the game process that a rootkit would. This is one reason why Linux's dynamic linker automatically ignores LD_PRELOAD for setuid and setgid binaries, and why the Vulkan loader ignores user-defined layer paths (VK_LAYER_PATH, VK_ADD_LAYER_PATH) when running with elevated privileges. You should only inject MangoHud into processes you trust, and you should always install it from your distribution's official repositories or the Flathub Flatpak -- never from unverified third-party sources.

Lutris

In Lutris, enable advanced options in the system settings for the game, then add mangohud to the Command Prefix field. Alternatively, set MANGOHUD=1 in the game's environment variables section.

Gamescope

If you are running games through gamescope (the Valve compositor used on Steam Deck and in SteamOS), the standard mangohud prefix does not work -- you must use mangoapp instead:

$ gamescope --mangoapp -- %command%

The mangoapp binary ships with MangoHud and is the correct integration path for gamescope. The old mangoapp Vulkan layer was removed in the 0.8 release series.

Heroic Games Launcher

In Heroic Games Launcher, open the settings for any game and enable the MangoHud toggle in the game options panel. As of Heroic Games Launcher v2.17.2 this is a built-in checkbox -- no launch string editing required. For older versions, set MANGOHUD=1 in the game's environment variables section.

Terminal Launch

$ mangohud /path/to/game-binary

The Config File

MangoHud's behavior is controlled by ~/.config/MangoHud/MangoHud.conf. The file does not exist by default. The fastest way to get a starting point is to generate the default config:

$ mkdir -p ~/.config/MangoHud && mangohud --print-config > ~/.config/MangoHud/MangoHud.conf
GUI alternative: GOverlay

If you prefer a graphical interface for configuring MangoHud, install goverlay from your package manager. GOverlay provides a point-and-click editor for all MangoHud config options and writes the config file on your behalf. It is available in the Arch extra repository, on Flathub, and via most major distribution repositories. For Arch-based systems, mangojuice is also available from the AUR as an alternative GUI.

A useful working config that adds temperatures and memory without cluttering the display:

~/.config/MangoHud/MangoHud.conf 
# Position: top-left | top-right | bottom-left | bottom-right | top-center
position=top-left
background_alpha=0.5
font_size=22

# FPS and frame timing
fps=1
frametime=1
frame_timing=1

# CPU: load, temp, power
cpu_stats=1
cpu_temp=1
cpu_power=1

# GPU: load, temp, power, per-process VRAM
gpu_stats=1
gpu_temp=1
gpu_power=1
vram=1

# System memory
ram=1

# Optional: cap display FPS for logging purposes
# fps_limit=144
# fps_limit can take decimal values (e.g., 59.94)

# Optional: secondary font size for less prominent metrics
# font_size_secondary=0  (defaults to 0.55 * font_size)

# Toggle overlay off by default (enable per-game via env)
# no_display=1

# Optional: set output folder for performance logging
# output_folder=/home/yourusername/mangologs

# Optional (0.8.2+): color for horizontal layout dividers (hex, no #)
# horizontal_separator_color=FF6600
Per-game overrides

You can create game-specific configs by placing a file named after the game's executable in the same directory. For example, ~/.config/MangoHud/gameexec.conf will override the global config only for that process. For Wine and Proton applications, the naming convention is different: use ~/.config/MangoHud/wine-gamename.conf where gamename is the Windows executable name without the .exe extension (case-sensitive). This lets you enable verbose metrics for benchmarking one game without cluttering every other title.

OpenGL compatibility workarounds

Two rarely documented config options can fix MangoHud rendering issues in specific OpenGL games. gl_bind_framebuffer=N rebinds the given framebuffer before MangoHud draws, which fixes rendering in games like Crusader Kings III. gl_dont_flip=1 prevents MangoHud from swapping the origin when using GL_UPPER_LEFT, which fixes display in the Ryujinx Nintendo Switch emulator. These options are not present in the generated default config and are only documented in the MangoHud README's parameter table.

GPU thermal throttle indicator

The throttling config option displays whether your GPU is currently being throttled due to power, current, temperature, or other limits. The indicator only appears when throttling is actively occurring -- it stays hidden during normal operation. Note that on NVIDIA 3000 series GPUs, this feature is currently disabled by default because it was causing input lag. On AMD RDNA3, version 0.8.2 resolved a bug where throttling was always falsely reported.

Keyboard Shortcuts

MangoHud ships with several default keyboard shortcuts that work while a game is running. All shortcuts use the XKB key naming convention -- Shift_R means the right Shift key, Shift_L means the left Shift key:

Shortcut Action
Shift_R + F12 Toggle the overlay on or off
Shift_L + F2 Start and stop performance logging to a CSV file
Shift_R + F11 Cycle the overlay position (top-left, top-right, etc.)
Shift_R + F10 Cycle through display presets
Shift_L + F1 Toggle FPS limiter
Shift_L + F3 Upload log to FlightlessMango.com
Shift_L + F4 Reload the config file without restarting the game
ActionToggle the overlay on or off
ActionStart and stop performance logging to a CSV file
ActionCycle the overlay position
ActionCycle through display presets
ActionToggle FPS limiter
ActionUpload log to FlightlessMango.com
ActionReload config without restarting the game

All shortcuts can be remapped in the config file using the corresponding keys: toggle_hud, toggle_logging, toggle_hud_position, toggle_preset, toggle_fps_limit, reload_cfg, and upload_log. On Wayland, keybind support was significantly improved in the 0.8 release series.

Performance Logging and Benchmarking

MangoHud can log all displayed metrics to a CSV file for offline analysis and benchmarking comparisons. To use logging, you must first set output_folder in your config to a valid path where MangoHud can write files:

~/.config/MangoHud/MangoHud.conf (logging section) 
# Required: set a folder where log files will be written
output_folder=/home/yourusername/mangologs

# Optional: log only the first N seconds after toggle
# log_duration=60

# Optional: begin logging automatically on game launch
# autostart_log=5

Once output_folder is set, press Shift_L+F2 to start logging and press it again to stop. Log files are named with the game executable and a timestamp. The log captures every frame with a timestamp, so you can reconstruct exact frame pacing over an entire benchmark run. This is useful for comparing driver versions, Proton versions, or graphics settings changes with a repeatable test sequence.

Automated logging

Set autostart_log=5 in your config and MangoHud will begin logging automatically 5 seconds after the game launches -- no keyboard input required. The value is a delay in seconds, not a toggle. To also cap how long the log runs, set log_duration=60 separately. These two options work independently: autostart_log controls when logging starts, log_duration controls when it stops. Together they are useful for headless benchmarking or reproducible timed captures.

Analyzing Logs: mangoplot and FlightlessMango.com

MangoHud ships with mangoplot, a local plotting script that processes a folder of CSV log files and generates stacked 1D framerate heatmaps for easy visual comparison across runs. Each benchmark run becomes a row in a stacked 2D chart, so you can compare frame rates across multiple sessions at a glance.

"Takes each log file, makes a 1D heatmap of its framerates."

-- MangoHud README.md, mangoplot description

To use it, point it at your log folder:

$ mangoplot /home/yourusername/mangologs/

For online analysis, logs can be uploaded directly to FlightlessMango.com using the Shift_L+F3 keybind (requires upload_logs=1 in config) or via the website directly. The site generates frametime graphs and summary tables showing 1% lows, average framerate, and 97th percentile results in both table and horizontal bar chart formats. Uploaded benchmarks are public and shareable by URL, making them practical for comparing results across hardware, driver versions, or Proton releases.

A single benchmark run tells you almost nothing. Frame rate varies with ambient thermals, background processes, compositor state, and which assets are cached. To produce meaningful data: run the same scene at least three times, discard the first run (cold cache), and compare the remaining two for consistency. If they diverge by more than 5% on average FPS, your test sequence is not reproducible -- something external is interfering.

Use autostart_log=5 combined with log_duration=60 for timed captures that do not require keyboard input, and use the same in-game position and movement path each time. MangoHud's CSV output includes per-frame timestamps, so you can compute variance, percentile distributions, and stutter metrics offline. The mangoplot heatmap is particularly effective for visual comparison across runs because it surfaces patterns that raw numbers flatten: a heatmap stripe with a warm band in the middle reveals a thermal throttle event that an average FPS figure would hide entirely.

For hardware comparisons, also log cpu_power and gpu_power alongside frame data. Two systems might produce similar FPS, but one draws 40% more power -- MangoHud's gpu_efficiency (frames per joule) metric surfaces this tradeoff directly.

Multi-GPU and Intel Support

MangoHud 0.8 added the ability to display multiple GPUs simultaneously. If you have a discrete GPU and an integrated GPU in use, you can list both with the gpu_list parameter. This is particularly useful on hybrid graphics laptops where you want to confirm which GPU is actually rendering your game.

Intel discrete and integrated GPU support was added in 0.8, using the i915 and xe kernel drivers. Temperature readings from Intel GPUs require Linux kernel 6.13 or higher -- this support landed through i915's hwmon interface. Fan speed reporting requires Linux kernel 6.12 or higher and is available on both i915 and xe. Power usage reporting is not available for Intel integrated GPUs due to a lack of hwmon interface on Intel's side -- this is a known upstream limitation tracked at the i915 and xe kernel issue trackers and is not something MangoHud can work around. Temperature readings are available on i915 only; the xe driver does not yet expose them.

GPU usage and memory usage on Intel currently reflects per-process consumption rather than a total system figure, which is a consequence of how the i915 and xe DRM interfaces expose data -- also tracked upstream. AMD and NVIDIA have been supported for significantly longer and work across a wide range of driver versions without manual intervention.

There is one additional requirement for Intel GPU usage statistics. By default, the GPU profiling sysfs interface is disabled. To enable it, run the following as root:

# echo N | sudo tee /sys/class/drm/renderD*/device/profiling

Without this step, MangoHud will not be able to read GPU load on Intel hardware. Note that this setting does not persist across reboots -- you can automate it via a udev rule or systemd unit if needed.

Security tradeoff: GPU profiling exposes telemetry

The Intel GPU profiling sysfs interface is disabled by default for a reason. Enabling it exposes per-process GPU usage data through /sys/class/drm/renderD*/device/profiling, which means any local user or process on the system can read GPU activity metrics. On a shared system or a machine running untrusted workloads, this telemetry could be used to fingerprint what applications are running based on their GPU usage patterns -- a known side-channel vector. On a single-user gaming desktop this tradeoff is generally acceptable, but if you are automating it via a udev rule on a machine that also serves as a development server or runs containers, consider whether the exposure is justified. The setting does not grant write access or control over the GPU, only read access to usage statistics.

Persistent Intel GPU profiling via udev

To make the Intel profiling sysfs interface enable automatically at boot, create a udev rule at /etc/udev/rules.d/99-mangohud-intel-profiling.rules with the content: ACTION=="add", SUBSYSTEM=="drm", KERNEL=="renderD*", RUN+="/bin/sh -c 'echo N > /sys/%p/device/profiling'". This triggers whenever a render node appears and writes the profiling flag immediately. The alternative is a oneshot systemd unit that runs echo N | tee /sys/class/drm/renderD*/device/profiling after the drm subsystem initializes. The upstream issues for per-process vs. system-wide usage reporting on Intel are tracked at i915 kernel #14153 and xe kernel #4861.

Broader Hardware Support in 0.8.2

The 0.8.2 release extended hardware coverage beyond the typical AMD/NVIDIA/Intel trio. The following platforms now have MangoHud support:

  • Panfrost (ARM Mali) -- Panfrost-driven GPUs, common on ARM SBCs and some Chromebooks, are now supported. This makes MangoHud usable on platforms like the RK3588 running mainline Linux.
  • Panthor (ARM Mali-G710+) -- The Panthor DRM driver, which covers Mali-G710 and newer ARM GPUs, was added in 0.8.1 and carries forward in 0.8.2. This is relevant for newer ARM SoCs targeting desktop-class GPU compute and Vulkan rendering.
  • Qualcomm KGSL -- Devices running the Qualcomm kernel driver (KGSL) are now tracked. This covers Snapdragon-based Linux systems including early Snapdragon X Elite hardware running native Linux.
  • APM XGene -- Applied Micro XGene ARM server platforms are now supported.
  • AMD APU v3_0 gpu_metrics -- The amdgpu v3_0 gpu_metrics interface is now read, enabling correct data on newer AMD APUs that use the updated metrics table format.
  • RAPL with AMD CPU power -- RAPL (Running Average Power Limit) can now be used to read AMD CPU power alongside existing AMD GPU reporting.

These additions make MangoHud meaningfully useful outside the x86 desktop gaming context, covering handheld Linux gaming hardware and ARM developer boards running Vulkan workloads. The 0.8.2 release also quietly resolved a persistent issue where MangoHud would falsely report thermal throttling on AMD RDNA3 GPUs -- a problem that had been frustrating users of RX 7000 series cards since the throttling indicator was introduced.

GTK-4 applications are intentionally blacklisted

MangoHud 0.8.2 added all GTK-4 apps to its internal blacklist. This means MangoHud will not inject into GTK-4-based launchers, file managers, or applications. This is intentional -- GTK-4 apps were causing crashes and rendering issues. If you try to run a GTK-4 app with MangoHud and the overlay does not appear, this is expected behavior, not a broken install.

Presets and Per-Game Configs

MangoHud includes a presets system that lets you define multiple display configurations and switch between them at runtime without restarting the game. Presets are cycled with Shift_R+F10. MangoHud ships with five built-in presets, and the default cycle order is -1,0,1,2,3,4:

  • -1 -- User-defined preset (reads from your presets.conf file if present; skipped if no user presets are defined)
  • 0 -- No HUD (overlay hidden)
  • 1 -- FPS only
  • 2 -- Horizontal compact layout
  • 3 -- Extended view
  • 4 -- Detailed view

User-defined presets can be created in ~/.config/MangoHud/presets.conf. This file uses the same config syntax as MangoHud.conf, with each preset block separated by a [preset N] header. You can also point MangoHud to a custom presets file at runtime using the MANGOHUD_PRESETSFILE=/path/to/config environment variable, which is particularly useful in Flatpak sandboxes. This is practical when you want a minimal FPS-only overlay for regular play but a full diagnostic view for troubleshooting without touching the main config file.

Per-game configs work by creating a file named after the game's executable in the same MangoHud config directory. For example, ~/.config/MangoHud/RimWorld.conf will override the global config only when RimWorld is running. For Wine and Proton games, the file is named wine-RimWorld.conf (the executable name without .exe, case-sensitive). The config file search order is: local directory next to the executable, then XDG_CONFIG_HOME/MangoHud/<app_name>.conf, then the global MangoHud.conf.

Pairing with GameMode

GameMode is a performance daemon by Feral Interactive that applies CPU governor changes, I/O priority tweaks, and other optimizations when a game is running. MangoHud and GameMode can be combined in a single launch command:

$ gamemoderun mangohud %command%

MangoHud can also display whether GameMode is currently active using the gamemode config option, so you can confirm the performance profile is engaged from within the overlay.

Wayland Support

MangoHud works best under X11. Wayland support has improved substantially -- keybind handling in particular was a weak point that was addressed in the 0.8 series -- but some Wayland compositors may still exhibit issues where the overlay does not appear in all applications or where mangoapp crashes when an X11 session disappears.

MangoHud 0.8.2 fixed a specific crash that occurred on LLVMPIPE (the Mesa software renderer) when MangoHud tried to check vsync status, and fixed an X11 crash triggered when $DISPLAY was not set. Both fixes improve reliability in mixed Wayland/X11 environments.

If you are running a Wayland session and the overlay is missing, the most reliable workaround is to confirm you are using a recent enough MangoHud version, verify that Vulkan support is installed for your GPU, and check whether the game itself is running under XWayland rather than native Wayland. For Flatpak Steam on Wayland, you may also need to grant the org.freedesktop.Flatpak talk name: flatpak override --user --talk-name=org.freedesktop.Flatpak com.valvesoftware.Steam.

Security Considerations for Linux Gaming Overlays

MangoHud is open-source, widely audited by the community, and distributed through official distribution repositories. That said, using any overlay tool that injects code into a running process comes with security implications that are worth understanding explicitly.

Supply Chain Risk: Always Verify Your Source

In March 2026, the FBI publicly requested victims of malware-infected games that had been distributed through Steam between May 2024 and January 2026. Titles including PirateFi, BlockBasters, and others had embedded info-stealers that harvested credentials, cryptocurrency wallets, and browser data. Separately, in February 2026, a malicious mod in the Steam Workshop for People Playground masqueraded as a legitimate top-rated mod, then replicated itself by replacing other installed mods with infected copies and destroying save files. These incidents underscore a broader supply chain risk in the Linux gaming ecosystem: if the game or tool you are running has been tampered with, anything that loads into the same process -- including MangoHud -- inherits that compromised context.

MangoHud itself has no known CVEs and is maintained transparently at github.com/flightlessmango/MangoHud. To minimize supply chain risk: install MangoHud only from your distribution's official repositories (pacman, apt, dnf) or from the Flathub Flatpak (org.freedesktop.Platform.VulkanLayer.MangoHud). Avoid downloading MangoHud builds from forums, Discord servers, or unverified GitHub forks. If you are using the AUR on Arch-based systems, always review the PKGBUILD before building.

What LD_PRELOAD Injection Means for Your Threat Model

MangoHud injects into the game process using LD_PRELOAD (for OpenGL via DLSYM) and as a Vulkan implicit layer. Both mechanisms grant the injected code full access to the process's memory, file descriptors, and network connections. This is the same level of access that user-space rootkits exploit -- the MITRE ATT&CK framework catalogs this under T1574.006. MangoHud uses it legitimately, but the implication is that if a malicious shared library were placed in a location where the dynamic linker searches before the real MangoHud library, it would be loaded in its place.

Linux mitigates this in several ways. The dynamic linker ignores LD_PRELOAD for setuid and setgid binaries. The Vulkan loader ignores user-defined layer paths (VK_LAYER_PATH, VK_ADD_LAYER_PATH, VK_IMPLICIT_LAYER_PATH) when running with elevated privileges. Flatpak restricts LD_PRELOAD manipulation from outside the sandbox. Still, on a standard desktop session, any process running under your user account can set LD_PRELOAD for its children. The practical defense is to keep your MangoHud installation from a trusted source, verify the Vulkan layer manifest points to the expected library path (/usr/share/vulkan/implicit_layer.d/MangoHud.x86_64.json on Arch), and monitor for unexpected entries in /etc/ld.so.preload or the environment of long-running processes.

What would happen if

An attacker placed a malicious libMangoHud.so in a directory searched before the system library path -- say, in a game's local directory or via a poisoned LD_LIBRARY_PATH? The dynamic linker would load the attacker's library instead of the real one. Your game would appear to run normally, the overlay might even still work if the malicious library wraps the real one, but the attacker's code would now have full access to the process's memory -- including any credentials, API keys, or session tokens the game handles. This is not hypothetical: it is exactly how the Symbiote malware family operated on Linux systems, and it is the reason that verifying your MangoHud source matters as much as verifying the game itself.

Verify your MangoHud installation

Select your installation type to see the verification commands you should run:

-- select your package manager above --
Installation method security comparison
Method
Sandbox isolation
Supply chain
pacman / apt / dnf
None -- runs in user session
Strong -- distro-signed packages
Flatpak (Flathub)
bubblewrap -- process isolation
Good -- Flathub review + runtime
AUR (mangohud-git)
None -- runs in user session
Review PKGBUILD -- user-submitted
Manual build from GitHub
None -- runs in user session
Good -- verify commit signatures
Forum / Discord download
None
Unverifiable -- avoid entirely

Flatpak Sandboxing as a Security Boundary

If you run Steam as a Flatpak, you gain a meaningful security layer that native package installations do not provide. Flatpak's bubblewrap sandbox restricts the application's access to host files, device nodes, and processes by default. The reason MangoHud must be installed as a separate Flatpak (org.freedesktop.Platform.VulkanLayer.MangoHud) rather than using the system package is precisely because the sandbox blocks the LD_PRELOAD path that the system library would use. This is a feature, not a limitation. When you grant config access with flatpak override --user --filesystem=xdg-config/MangoHud:ro, the :ro flag enforces read-only access -- the Flatpak can read your overlay config but cannot modify it or write to other parts of your filesystem. Avoid using broader filesystem overrides like --filesystem=host or --filesystem=home as workarounds, because these effectively disable the sandbox for your home directory and defeat the isolation model entirely.

Consider this

Flatpak's sandbox blocks LD_PRELOAD from the host -- which is why MangoHud needs its own Flatpak build. But that same sandbox also means a compromised game inside the Flatpak cannot easily read your SSH keys, browser cookies, or GPG keyring from your home directory. If you are running untrusted Proton titles from outside your main Steam library, does the sandbox tradeoff change your calculation about Flatpak vs. native Steam?

01
MangoHud's injection uses the same LD_PRELOAD and Vulkan layer mechanism cataloged as MITRE ATT&CK T1574.006. Understand the tradeoff.
02
Install only from official repos, Flathub, or verified GitHub commits. Never from forums, Discord, or unverified third-party sources.
03
Flatpak Steam adds a real security boundary. The :ro config override preserves least privilege. Avoid --filesystem=host workarounds.
04
Intel GPU profiling sysfs is off by default for a reason. Enabling it exposes telemetry. Acceptable on a gaming desktop, worth auditing on shared machines.

How to Install and Configure MangoHud on Linux

Step 1: Install MangoHud via your package manager

On Arch Linux run sudo pacman -S mangohud lib32-mangohud. On Debian or Ubuntu run sudo apt install mangohud. On Fedora run sudo dnf install mangohud. On openSUSE run sudo zypper install mangohud mangohud-32bit. Including the 32-bit package ensures that 32-bit games and Proton titles can also load the overlay.

Step 2: Generate and edit the config file

Run mkdir -p ~/.config/MangoHud followed by mangohud --print-config > ~/.config/MangoHud/MangoHud.conf to create an editable default config. Open the file and enable the metrics you want, such as cpu_temp=1, gpu_temp=1, ram=1, and vram=1. You can also set position, font_size, and background_alpha to your preference.

Step 3: Launch a game with MangoHud

For Steam games, right-click the game, choose Properties, and add mangohud %command% to the Launch Options field. For non-Steam games run mangohud /path/to/game from the terminal. DLSYM hooking for OpenGL is enabled by default -- if a specific game crashes because of it, disable it with MANGOHUD_DLSYM=0 %command%.

Step 4: Toggle and customize the overlay in-game

Press Shift_R+F12 to toggle the overlay on or off while in game. To log performance data, first set output_folder in your config, then press Shift_L+F2 to start and stop logging to a CSV file. Press Shift_L+F4 to reload the config file without restarting the game. Adjust position, colors, font size, and visible metrics by editing MangoHud.conf. For finer control, create a per-game config file using the game executable name in the same directory.

Frequently Asked Questions

What is MangoHud and what metrics does it display?

MangoHud is an open-source Vulkan and OpenGL overlay for Linux that displays real-time performance data directly on screen while gaming. It shows FPS, frame times, CPU and GPU usage percentages, CPU and GPU temperatures, RAM and VRAM usage, and more. It also powers the built-in performance overlay on the Steam Deck.

Does MangoHud work with Wayland?

MangoHud works best under X11. Wayland support has improved over time, particularly with keybind handling added in the 0.8 release series, but some Wayland compositors may still experience limitations such as the overlay not appearing in all applications.

How do I enable MangoHud for Steam games?

Right-click the game in your Steam library, choose Properties, and add mangohud %command% to the Launch Options field. This works for both native Linux games and Proton-run titles. For Vulkan games you can also set the MANGOHUD=1 environment variable globally.

Where is the MangoHud config file located?

The main configuration file is at ~/.config/MangoHud/MangoHud.conf. You can generate a default config to edit by running mangohud --print-config > ~/.config/MangoHud/MangoHud.conf. Game-specific configs can be placed in the same directory using the game's executable name as the filename. The config can also be overridden at runtime using the MANGOHUD_CONFIG environment variable for quick, per-launch parameter changes.

How do I log performance data and what is the keybind?

First set output_folder=/path/to/folder in your MangoHud.conf -- logging will not work without a valid output path. Then press Shift_L+F2 (left Shift + F2) to start and stop logging. Logs are saved as CSV files. They can be analyzed locally with the bundled mangoplot script or uploaded to FlightlessMango.com for online graphs.

Why is MangoHud not showing GPU usage on Intel hardware?

Intel GPU usage data requires the profiling sysfs interface to be enabled. Run the following as root: echo N | sudo tee /sys/class/drm/renderD*/device/profiling. Without this, MangoHud will silently omit GPU load on Intel hardware, whether you are using the i915 or xe driver. The setting does not survive a reboot -- automate it with a udev rule or systemd unit. Temperature readings additionally require Linux kernel 6.13 or above and are only available on the i915 driver, not the xe driver. Fan speed requires Linux kernel 6.12 or above. Integrated Intel GPUs carry an additional constraint: Intel has not exposed a hwmon power interface for them, so CPU and GPU power draw figures will be unavailable regardless of kernel version -- this is a known upstream limitation, not a MangoHud bug.

How do I use MangoHud with the Flatpak version of Steam?

The system-installed MangoHud package is sandboxed out of Flatpak apps and will not inject. Install the Flatpak build instead: flatpak install flathub org.freedesktop.Platform.VulkanLayer.MangoHud. Then grant config access with flatpak override --user --filesystem=xdg-config/MangoHud:ro. To enable MangoHud globally across all Flatpak Steam games, run flatpak override --user --env=MANGOHUD=1 com.valvesoftware.Steam. The older com.valvesoftware.Steam.Utility.MangoHud package is no longer actively maintained.

Environment Variables and Less-Documented Options

MangoHud exposes several environment variables that are not prominently featured in most guides but are frequently needed in edge-case setups.

MANGOHUD_FPS_LIMIT -- As of 0.8, you can set the FPS limit for a specific application without modifying the config file: MANGOHUD_FPS_LIMIT=60 mangohud %command%. This overrides any fps_limit value set in the config file for that launch. It accepts decimal values (e.g., 59.94 for broadcast-standard frame rates), which is also available through the fps_limit config key as of 0.8.2.

MANGOHUD_PRESETSFILE -- Points MangoHud at a custom presets file at runtime: MANGOHUD_PRESETSFILE=/path/to/custom-presets.conf mangohud %command%. This is especially useful in Flatpak sandboxes where the default config path may not be writable, or when you want to maintain separate preset sets for different gaming contexts -- competitive play versus streaming capture, for example.

MANGOHUD_CONFIG -- Override the config file entirely for a single launch: MANGOHUD_CONFIG=cpu_temp,gpu_temp,fps mangohud %command%. The value can be a comma-separated list of config options, or a file path. This is useful for testing new config values without overwriting your working MangoHud.conf.

MANGOHUD_OUTPUT -- Override the output folder for log files on a per-launch basis without touching your config file. Useful for organizing benchmark sessions into separate directories.

Application Blacklisting: What MangoHud Refuses to Inject Into

MangoHud maintains an internal blacklist of applications where injection would cause crashes or rendering problems. As of 0.8.2, this list includes all GTK-4 applications (launchers, file managers, desktop tools) and specifically the Marvel Rivals launcher. If you run a GTK-4 application with MANGOHUD=1 set globally in your environment and the overlay never appears, this is intentional, not a bug. The blacklist is hardcoded in the MangoHud source and cannot be overridden at runtime. The Feral launcher (used by some native Linux game releases) also has a specific workaround in 0.8.2: MangoHud will not inject if the Feral launcher uses its exec option.

This distinction matters if you are troubleshooting a missing overlay -- a blacklisted application will silently not display the HUD, whereas a mis-configured install on a supported application will usually fail with a logged error you can find by running the game from a terminal with MANGOHUD_LOG_LEVEL=debug.

Network Metrics

MangoHud can display network interface activity using the network config option. The displayed color is controlled by network_color in your config file (hex value, no leading #). MangoHud reads from the first non-loopback network interface it finds, which on most systems is your primary Ethernet or WiFi adapter. If you are monitoring a game over a VPN or a secondary interface, the reading may not reflect the game's actual network usage -- this is a known limitation of how MangoHud reads network statistics.

Runtime Control with mangohudctl

MangoHud ships with mangohudctl, a command-line binary for controlling a running MangoHud instance from outside the game window. To use it, first enable the control socket in your config file:

# control=mangohud

You can also use control=mangohud-%p where %p is replaced by the process ID, useful when running multiple games simultaneously. Once the socket is active, mangohudctl can toggle the overlay, change presets, start and stop logging, and modify config values at runtime without restarting the game or touching the config file. This is particularly useful for scripted benchmark automation or for streamers who want to toggle the overlay from a secondary terminal or script without interrupting gameplay input.

Debug logging

If MangoHud is not loading at all, run the game from a terminal with MANGOHUD_LOG_LEVEL=debug mangohud %command% and watch the output. Common issues include the overlay library not being found (especially on 32-bit games without lib32-mangohud installed), the Vulkan layer not registering (check vulkaninfo | grep MangoHud), and permission errors on Intel profiling sysfs paths. The debug output will tell you exactly which library path MangoHud attempted to load from, which is often the fastest way to diagnose a silent failure.

Verifying the Vulkan layer is registered

Before troubleshooting game-specific issues, confirm that MangoHud's Vulkan layer is registered on your system by running vulkaninfo --summary 2>&1 | grep -i mango. If MangoHud does not appear in the layer list, the package may not have installed the layer manifest correctly. On Arch, the manifest is at /usr/share/vulkan/implicit_layer.d/MangoHud.x86_64.json (and MangoHud.x86.json for 32-bit). On Flatpak, the layer is registered inside the runtime and does not appear in the host system's vulkaninfo output -- this is expected. Also verify that the environment variable DISABLE_MANGOHUD=1 is not set in your shell profile, as this will suppress the overlay globally.

Sources and References

Technical details in this guide are drawn from official documentation and verified sources.

$ man mangohud
An open-source Vulkan and OpenGL overlay for Linux that displays real-time performance metrics including FPS, frame times, CPU and GPU load, temperatures, and memory usage. Maintained at github.com/flightlessmango/MangoHud and used as the overlay engine on the Steam Deck.
$ man vulkan
A low-overhead, cross-platform graphics and compute API developed by the Khronos Group. Vulkan gives applications direct control over the GPU, reducing driver overhead compared to OpenGL. It is the preferred rendering backend for modern Linux gaming and for tools like MangoHud and DXVK.
$ man proton
Valve's compatibility layer built on Wine and DXVK that allows Windows games to run on Linux through Steam. MangoHud works with Proton-run titles via Steam Launch Options.
$ man frame-time
The time in milliseconds that the GPU takes to render a single frame. Consistent frame times produce smooth gameplay; irregular frame times cause perceived stuttering even when average FPS looks acceptable. MangoHud displays a frame time graph to surface these irregularities.
$ man linux-gaming
Gaming on Linux has matured significantly with Proton, Steam Deck, and projects like MangoHud, GameMode, and Mesa. Many Windows titles now run on Linux without manual configuration, and native Linux releases from major studios continue to grow.
$ man mangohudctl
A command-line binary shipped with MangoHud for controlling a running overlay instance via a Unix socket. Requires setting control=mangohud in the config file. Enables toggling the overlay, switching presets, and modifying config values at runtime.
^ back to top