MangoHud — Vulkan and OpenGL Overlay for Gaming Performance Monitoring

Introduction

MangoHud is a Vulkan and OpenGL overlay for monitoring system performance while gaming on Linux. Inspired by tools like MSI Afterburner and RivaTuner on Windows, it injects a configurable HUD into running games that shows FPS, frame timing, temperatures, and hardware utilization without leaving the game.

What MangoHud Does

• Displays real-time FPS, frame time graphs, and percentile metrics as an in-game overlay
• Shows CPU and GPU temperatures, clock speeds, load percentage, and power draw
• Reports RAM and VRAM usage, IO throughput, and battery status on laptops
• Logs performance data to CSV files for offline analysis and benchmarking
• Supports per-game and global configuration through a simple text config file

Architecture Overview

MangoHud works as a Vulkan layer and an OpenGL preload library. For Vulkan games, it registers as an implicit layer that intercepts swapchain present calls to draw the overlay. For OpenGL, it uses LD_PRELOAD to hook into the GL context. Sensor data comes from sysfs, libsensors, and NVML (for NVIDIA GPUs). A companion tool called MangoApp provides a standalone window for monitoring without injection.

Self-Hosting & Configuration

• Install from your distribution's package manager or compile from source with meson
• Create a config file at ~/.config/MangoHud/MangoHud.conf to customize displayed metrics
• Toggle the overlay at runtime with a configurable keybind (default: Right Shift + F12)
• Use MANGOHUD=1 as an environment variable or add mangohud %command% to Steam launch options
• Enable logging with log_duration=30 to record benchmark data to CSV

Key Features

• Highly customizable HUD layout with toggleable metrics via config file
• Frame time graph overlay for identifying stutter and inconsistent frame pacing
• Benchmark logging with min/max/average FPS and percentile output
• Integration with Gamescope for HDR and display management awareness
• Works with both native Linux games and Windows games running through Proton/Wine

Comparison with Similar Tools

• MSI Afterburner + RivaTuner — the Windows equivalent; MangoHud provides similar functionality natively on Linux
• Gamescope — a Wayland compositor for gaming that can embed MangoHud overlays with extra features
• vkBasalt — post-processing layer for Vulkan games; focused on visual effects rather than monitoring
• GOverlay — a GUI for configuring MangoHud, vkBasalt, and ReplaySorcery settings graphically

FAQ

Q: Does MangoHud work with Proton and Wine games? A: Yes. MangoHud works with both native and Proton/Wine games by injecting into the Vulkan or OpenGL layer.

Q: How do I customize which metrics are shown? A: Edit ~/.config/MangoHud/MangoHud.conf and list the metrics you want (e.g., fps, gpu_temp, cpu_load, frametime).

Q: Can I use it for benchmarking? A: Yes. Enable logging in the config and MangoHud records frame data to CSV files for analysis.

Q: Does it support NVIDIA GPUs? A: Yes. MangoHud reads NVIDIA sensor data through NVML and supports both NVIDIA and AMD GPUs.

Sources

• https://github.com/flightlessmango/MangoHud