mangohud
Display performance metrics overlay in games
TLDR
Use mangohud on top of an application
Change overlay position
Change overlay verbosity
Toggle overlay visibility
SYNOPSIS
mangohud [GLOBAL_OPTIONS] <COMMAND> [ARGUMENTS...]
MANGOHUD=1 <COMMAND> [ARGUMENTS...]
MANGOHUD_CONFIG="<config_string>" <COMMAND> [ARGUMENTS...]
PARAMETERS
--config <path>
Specifies a custom configuration file path instead of the default ~/.config/MangoHud/MangoHud.conf.
--d3d12
Forces MangoHud to hook into D3D12 (via DXVK). Useful when auto-detection fails or for specific setups.
--vulkan
Forces MangoHud to hook into Vulkan. Useful when auto-detection fails or for specific setups.
--gl
Forces MangoHud to hook into OpenGL. Useful when auto-detection fails or for specific setups.
--full
Enables a comprehensive set of default statistics on the overlay. Equivalent to setting the environment variable MANGOHUD_FULL=1.
--fps-only
Displays only the frames per second (FPS) counter on the overlay. Equivalent to setting the environment variable MANGOHUD_CONFIG=fps.
--version
Displays the MangoHud version information and exits.
--help
Displays a help message with available command-line options and exits.
DESCRIPTION
MangoHud is an open-source performance overlay for Vulkan, OpenGL, and D3D11/12 applications running on Linux. It displays real-time metrics such as frames per second (FPS), frame timings, CPU and GPU utilization, temperature, clock speeds, RAM and VRAM usage, and more. Highly customizable via a configuration file or environment variables, MangoHud allows users to select specific metrics, adjust their layout, colors, and font. It's a vital tool for Linux gamers and developers to monitor system performance during gameplay, diagnose bottlenecks, or simply keep an eye on hardware statistics. It works by injecting itself into the target application's process, typically using the LD_PRELOAD mechanism for OpenGL/Vulkan libraries or integrating with DXVK/Proton.
CAVEATS
MangoHud primarily functions with Vulkan, OpenGL, and D3D11/12 (via DXVK/Proton) applications. Its reliance on LD_PRELOAD might occasionally conflict with certain sandboxed environments, specific anti-cheat mechanisms, or applications that do not use these graphics APIs. While generally low, there can be a minor performance overhead, especially with extensive logging or many metrics enabled. Configuration for the actual HUD content is largely managed through environment variables or dedicated configuration files, not direct command-line arguments to the mangohud wrapper script itself.
CONFIGURATION METHODS
The behavior and appearance of the MangoHud overlay are extensively customizable through several methods:
- Configuration File: The primary method is a file located at ~/.config/MangoHud/MangoHud.conf. Users can create or modify this file to specify which metrics to display, their position, colors, font sizes, and more. Per-application configurations can also be created (e.g., MangoHud_GameTitle.conf).
- Environment Variable (MANGOHUD_CONFIG): A temporary or per-launch configuration can be provided via the MANGOHUD_CONFIG environment variable. This allows passing a comma-separated string of options directly to the application, overriding or supplementing the config file. For example: MANGOHUD_CONFIG="fps,cpu_temp,gpu_temp" mangohud ./mygame.
- Environment Variable (MANGOHUD=1): Simply setting MANGOHUD=1 before launching an application enables the HUD with default settings, loading from the config file if present.
INTEGRATION WITH PROTON/STEAM PLAY
MangoHud is widely used with Steam Play (Proton) for Windows games running on Linux. It can be easily enabled via Steam's launch options for a specific game:
MANGOHUD=1 %command%
For custom configurations, use:
MANGOHUD_CONFIG="fps,gpu_stats" %command%
This ensures MangoHud injects into the Proton environment and displays the overlay for the Windows game.
HISTORY
MangoHud was developed by FlightlessMango and emerged as a popular open-source solution for performance monitoring in the Linux gaming ecosystem. Initially focused on Vulkan, its capabilities were later extended to OpenGL and D3D11/12 (via DXVK), making it a versatile tool for a wide range of games and applications. Its ease of use and extensive customization options quickly led to its widespread adoption among Linux gamers and distribution packagers.
SEE ALSO
gamemoderun(1), vulkaninfo(1), glxinfo(1), perf(1)