DOCSEARCHbyAlgolia
Submit Docs

MangoHud Documentation

repository·master·Indexed 27 days ago

https://github.com/flightlessmango/mangohud

A high-performance Vulkan and OpenGL overlay for monitoring real-time performance metrics such as FPS, temperatures, and CPU/GPU load during gaming. Includes documentation for the standard overlay, installation via source or package managers, and MangoHud Next, which features a YAML-configurable server-client architecture for custom HUD layouts and JSON metric snapshots.

Tokens
6.4K
Snippets
12
Records
44
Agent score
94%

What's inside MangoHud

  3. Log FPS data and visualize results

    master

    To log FPS data, you must define a valid path for output_folder in your MangoHud configuration. When logging is toggled (via Shift_L+F2), a file named after the game with a timestamp is created in that folder.

    Visualization Options

    • Online: Upload log files to FlightlessMango.com to generate frametime graphs and statistical summaries (1% min, average, 97th percentile).
    • Local: Use the included mangoplot script. Point it at a folder containing log files to generate 2D heatmap graphs for visual comparison between benchmarks.

  5. Run MangoHud with applications

    master

    To enable the MangoHud overlay, prefix your application command with mangohud or use environment variables.

    General usage: mangohud /path/to/app

    Steam: Add mangohud %command% to the game's launch options.

    Lutris: In System options (ensure advanced options are enabled), add mangohud to the Command prefix setting.

    Vulkan-only alternative: Set the environment variable MANGOHUD=1 in your shell profile.

  6. Configure MangoHud using configuration files

    master

    MangoHud uses configuration files to set options globally or per application. Files are loaded in the following priority order (highest priority first):

    1. MangoHud.conf located in the application's directory.
    2. Per-application configuration in ~/.config/MangoHud/:
      • Native applications: ~/.config/MangoHud/<application_name>.conf (case-sensitive executable name).
      • Wine/Proton applications: ~/.config/MangoHud/wine-<application_name>.conf (case-sensitive executable name without the .exe extension).
    3. Global configuration: ~/.config/MangoHud/MangoHud.conf.

    Example: For the game Overwatch.exe running via Wine, use ~/.config/MangoHud/wine-Overwatch.conf.

    If you run a game from the terminal with MangoHud enabled, it will print the names of the configuration files it is searching for in the terminal output.

  7. Configure MangoHud using environment variables

    master

    You can override or supplement configuration files using environment variables. These take priority over config files.

    • MANGOHUD_CONFIG: Set multiple options separated by commas (or + if values contain commas). Use read_cfg as the first parameter if you want to load the config file in addition to these variables.
    • MANGOHUD_CONFIGFILE: Specify a path to a specific configuration file. Useful for applications with generic names like java or python.
    • MANGOHUD_PRESETSFILE: Specify a path to a presets file. Useful for sandboxed environments like Flatpak.
    • MANGOHUD_OPENGL_LIBS: Specify a custom path to libMangoHud_opengl.so for testing.

    Example:

    MANGOHUD_CONFIG=cpu_temp,gpu_temp,position=top-right,height=500,font_size=32

    Note on delimiters: Since commas are used to separate options, if an option value requires a comma, use + as a delimiter instead. For example: MANGOHUD_CONFIG=fps_limit=60+30+0.

    MANGOHUD_CONFIG=cpu_temp,gpu_temp,position=top-right,height=500,font_size=32

  9. Locate and configure MangoHud Next configuration file

    master

    MangoHud Next uses a YAML configuration file located at $XDG_CONFIG_HOME/MangoHud/MangoHud.yml. If $XDG_CONFIG_HOME is not defined, it falls back to ~/.config/MangoHud/MangoHud.yml.

    If the file is missing or contains an invalid hud_table, the system falls back to a built-in default. The configuration file is automatically reloaded when its timestamp or size changes while MangoHud Next is running.

  10. Enable GPU usage profiling for Panfrost/Panthor drivers

    master

    To enable GPU usage metrics for Panfrost or Panthor drivers, you must manually enable profiling via sysfs:

    For Panfrost, use:

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

    For Panthor, use:

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

  12. Run an application with MangoHud Next

    master

    You can launch applications through the MangoHud Next launcher. This is required for OpenGL applications or mixed Vulkan/OpenGL environments.

    For standard command line usage:

    mangohud-next <application>

    For Steam, add the following to your application's launch options:

    mangohud-next %command%
    mangohud-next glxgears