LinuxCommandLibrary

mangohud

Display performance metrics overlay in games

TLDR

Use mangohud on top of an application

$ mangohud [command]
copy

Change overlay position
$ <RightShift F11>
copy

Change overlay verbosity
$ <RightShift F10>
copy

Toggle overlay visibility
$ <RightShift F12>
copy

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)

Copied to clipboard