Repository files navigation

A Vulkan and OpenGL overlay for monitoring FPS, temperatures, CPU/GPU load and more.

• MangoHud
  • Installation - Build From Source
    • Dependencies
    • Building with build script
  • Installation - Pre-packaged Binaries
    • GitHub releases
    • Arch-based distributions
    • Debian, Ubuntu
    • Fedora
    • Solus
    • openSUSE
    • Flatpak
  • Normal usage
  • OpenGL
  • Hud configuration
    • Environment Variables:MANGOHUD_CONFIG,MANGOHUD_CONFIGFILE, andMANGOHUD_PRESETSFILE
  • Vsync
    • OpenGL Vsync
    • Vulkan Vsync
  • Keybindings
  • Workarounds
  • FPS logging
    • Online visualization: FlightlessMango.com
    • Local visualization:mangoplot
  • Metrics support by GPU vendor/driver

If you wish to compile MangoHud to keep up to date with any changes - first clone this repository and cd into it:

git clone --recurse-submodules https://github.com/flightlessmango/MangoHud.gitcd MangoHud

Usingmeson to install "manually":

meson buildninja -C build install

By default, meson should install MangoHud to/usr/local. Specify install prefix with--prefix=/usr if desired.Add-Dappend_libdir_mangohud=false option to meson to not appendmangohud to libdir if desired (e.g. /usr/local/lib/mangohud).

To install 32-bit build on 64-bit distro, specify properlibdir:lib32 for Arch,lib/i386-linux-gnu on Debian-based distros. RPM-based distros usually install 32-bit libraries to/usr/lib and 64-bit to/usr/lib64.You may have to changePKG_CONFIG_PATH to point to correct folders for your distro.

CC="gcc -m32" \CXX="g++ -m32" \PKG_CONFIG_PATH="/usr/lib32/pkgconfig:/usr/lib/i386-linux-gnu/pkgconfig:/usr/lib/pkgconfig" \meson build32 --libdir lib32ninja -C build32 install

Install necessary development packages.

• gcc, g++
• or gcc-multilib, g++-multilib for 32-bit support
• meson >=0.54
• ninja (ninja-build)
• glslang
• libGL/libEGL (libglvnd, mesa-common-dev, mesa-libGL-devel etc)
• X11 (libx11-dev)
• XNVCtrl (libxnvctrl-dev), optional, use-Dwith_xnvctrl=disabled option withmeson to disable
• D-Bus (libdbus-1-dev), optional, use-Dwith_dbus=disabled option withmeson to disable
• wayland-client
• xkbcommon

Python 3 libraries:

• Mako (python3-mako or install withpip)

If distro's packagedmeson is too old and gives build errors, install newer version withpip (python3-pip).

You can also usebuild.sh script to do some things automatically like install dependencies, if distro is supported but it usually assumes you are running on x86_64 architecture.

To just build it, execute:

./build.sh build

You can also pass arguments to meson:

./build.sh build -Dwith_xnvctrl=disabled

Resulting files will be install to./build/release folder.

If you have compiled MangoHud from source, to install it, execute:

./build.sh install

You can then subsequently uninstall MangoHud via the following command

./build.sh uninstall

To tar up the resulting binaries into a package and create a release tar with installer script, execute:

./build.sh package release

or combine the commands, althoughpackage should also callbuild if it doesn't find the built libs:

./build.sh build package release

If you have built MangoHud before and suddenly it fails, you can try cleaning thebuild folder, execute:

./build.sh clean

Currently it just doesrm -fr build and clears subprojects.

NOTE: If you are running an Ubuntu-based, Arch-based, Fedora-based, or openSUSE-based distro, the build script will automatically detect and prompt you to install missing build dependencies. If you run into any issues with this please report them!

If you do not wish to compile anything, simply download the file underReleases, extract it, and from within the extracted folder in terminal, execute:

./mangohud-setup.sh install

If you are using an Arch-based distribution, installmangohud andlib32-mangohud from theextra/multilib repository.mangohud-git andlib32-mangohud-git are available on the AUR to be installed via your favourite AUR helper. These can help fix issues with the hud not activating when using stable releases from pacman!

If you are building it by yourself, you need to enable multilib repository, by editing pacman config:

sudo nano /etc/pacman.conf

and uncomment:

#[multilib]#Include = /etc/pacman.d/mirrorlist

then save the file and execute:

sudo pacman -Syy

If you are using Debian 11 (Bullseye) or later, Ubuntu 21.10 (Impish) or later, or distro derived from them, to install theMangoHud package, execute:

sudo apt install mangohud

Optionally, if you also need MangoHud for 32-bit applications,on Debian you can execute:

sudo apt install mangohud:i386

The 32-bit package is not available on Ubuntu.

If you are using Fedora, to install theMangoHud package, execute:

sudo dnf install mangohud

If you are using Solus, to installMangoHud simply execute:

sudo eopkg it mangohud

If you run openSUSE Leap or Tumbleweed you can get Mangohud from the official repositories.There are two packages,mangohud for 64bit andmangohud-32bit for 32bit application support.To have Mangohud working for both 32bit and 64bit applications you need to install both packages even on a 64bit operating system.

sudo zypper in mangohud mangohud-32bit

Leap doesn't seem to have the 32bit package.

Leap 15.2

sudo zypper addrepo -f https://download.opensuse.org/repositories/games:tools/openSUSE_Leap_15.2/games:tools.reposudo zypper install mangohud

Leap 15.3

sudo zypper addrepo -f https://download.opensuse.org/repositories/games:tools/openSUSE_Leap_15.3/games:tools.reposudo zypper install mangohud

If you are using Flatpaks, you will have to add theFlathub repository for your specific distribution, and then, to install it, execute:

For flatpak:

flatpak install org.freedesktop.Platform.VulkanLayer.MangoHud

To enable MangoHud for all Steam games:

flatpak override --user --env=MANGOHUD=1 com.valvesoftware.Steam

To enable the MangoHud overlay layer for Vulkan and OpenGL, run :

mangohud /path/to/app

For Lutris games, go to the System options in Lutris (make sure that advanced options are enabled) and add this to theCommand prefix setting:

mangohud

For Steam games, you can add this as a launch option:

mangohud %command%

Or alternatively, addMANGOHUD=1 to your shell profile (Vulkan only).

OpenGL games may also needdlsym hooking, which is now enabled by default. Set theMANGOHUD_DLSYM env to0 to disable likeMANGOHUD_DLSYM=0 %command% for Steam.

Some Linux native OpenGL games overrides LD_PRELOAD and stops MangoHud from working. You can sometimes fix this by editing LD_PRELOAD in the start scriptLD_PRELOAD=/path/to/mangohud/lib/

To enable mangohud with gamescope you need to install mangoapp.gamescope --mangoapp -- %command%

Using normal mangohud with gamescope is not supported.

MangoHud comes with a config file which can be used to set configuration options globally or per application. Usually it is installed as/usr/share/doc/mangohud/MangoHud.conf.example orget a copy from here.

The priorities of different config files are:

1. /path/to/application/dir/MangoHud.conf
2. Per-application configuration in ~/.config/MangoHud:
   1. ~/.config/MangoHud/<application_name>.conf for native applications, where<application_name> is the case sensitive name of the executable
   2. ~/.config/MangoHud/wine-<application_name>.conf for wine/proton apps, where<application_name> is the case sensitive name of the executable without the.exe ending
3. ~/.config/MangoHud/MangoHud.conf

Example: For Overwatch, this would bewine-Overwatch.conf (even though the executable you run from Lutris isBattle.net.exe, the actual game executable name isOverwatch.exe).

If you start the game from the terminal with MangoHud enabled (for example by starting Lutris from the terminal), MangoHud will print the config file names it is looking for.

You can find an example config in /usr/share/doc/mangohud

GOverlay is a GUI application that can be used to manage the config

You can also customize the hud by using theMANGOHUD_CONFIG environment variable while separating different options with a comma. This takes priority over any config file.

You can also specify configuration file withMANGOHUD_CONFIGFILE=/path/to/config for applications whose names are hard to guess (java, python etc).

You can also specify presets file withMANGOHUD_PRESETSFILE=/path/to/config. This is especially useful when running mangohud in a sandbox such as flatpak.

You can also specify custom hud libraries for OpenGL usingMANGOHUD_OPENGL_LIBS=/path/to/libMangoHud_opengl.so. This is useful for testing MangoHud without modifying the installation on your system.

A partial list of parameters are below. See the config file for a complete list.Parameters that are enabled by default have to be explicitly disabled. These (currently) arefps,frame_timing,cpu_stats (cpu load),gpu_stats (gpu load), and each can be disabled by setting the corresponding variable to 0 (e.g., fps=0).

Example:MANGOHUD_CONFIG=cpu_temp,gpu_temp,position=top-right,height=500,font_size=32Because comma is also used as option delimiter and needs to be escaped for values with a backslash, you can use+ likeMANGOHUD_CONFIG=fps_limit=60+30+0 instead.

Note: Width and Height are set automatically based on the font_size, but can be overridden.

Note: RAPL is currently used for Intel and AMD Zen CPUs to show power draw withcpu_power which may be unreadable for non-root users due tovulnerability. The correspondingenergy_uj file has to be readable by corresponding user, e.g. by runningchmod o+r /sys/class/powercap/intel-rapl\:0/energy_uj as root, else the power shown will be0 W, though having the file readable may potentially be a security vulnerability persisting until system reboots.

Note: Thezenpower3 orzenergy kernel driver must be installed to show the power draw of Ryzen CPUs.

• -1 = Adaptive sync
• 0 = Off
• 1 = On
• n = Sync to refresh rate / n.

• 0 = Adaptive VSync (FIFO_RELAXED_KHR)
• 1 = Off (IMMEDIATE_KHR)
• 2 = Mailbox (VSync with uncapped FPS) (MAILBOX_KHR)
• 3 = On (FIFO_KHR)

Not all vulkan vsync options may be supported on your device, you can check what your device supports herevulkan.gpuinfo.org

• Shift_L+F2 : Toggle Logging
• Shift_L+F4 : Reload Config
• Shift_R+F12 : Toggle Hud
• Shift_R+F9 : Reset FPS metrics

Options starting with "gl_*" are for OpenGL.

• gl_size_query = viewport : Specify what to use for getting display size. Options are "viewport", "scissorbox" or disabled. Defaults to using glXQueryDrawable.
• gl_bind_framebuffer = 0..N : (Re)bind given framebuffer before MangoHud gets drawn. Helps with Crusader Kings III.
• gl_dont_flip = 1 : Don't swap origin if using GL_UPPER_LEFT. Helps with Ryujinx.

You must set a valid path foroutput_folder in your configuration to store logs in.

When you toggle logging (default keybind isShift_L+F2), a file is created with the game name plus a date & timestamp in youroutput_folder.

Log files can be visualized with two different tools: online and locally.

Log files can be (batch) uploaded toFlightlessMango.com, which will then take care of creating a frametime graph and a summary with 1% min / average framerate / 97th percentile in a table form and a horizontal bar chart form.

Notes:

• Uploaded benchmarks are public: you can share them with anyone by simply giving them the link.
• Benchmark filenames are used as legend in the produced tables and graphs, they can be renamed after the upload.

mangoplot is a plotting script that is shipped withMangoHud: on a given folder, it takes each log file, makes a 1D heatmap of its framerates, then stacks the heats maps vertically to form a 2D graph for easy visual comparison between benchmarks.

Example output:

_{^{Overwatch 2, 5950X + 5700XT, low graphics preset, FHD, 50% render scale}}

• GPU temperature fori915 requireslinux 6.13+
• Fan speed fori915 requireslinux 6.12+
• GPU temperature and vram temperature forxe requireslinux 6.15+
• Fan speed forxe requireslinux 6.16+
• GPU usage and memory usage shows usage of current process, not total system usage (it's an issue on intel's side)
  • https://gitlab.freedesktop.org/drm/i915/kernel/-/issues/14153
  • https://gitlab.freedesktop.org/drm/xe/kernel/-/issues/4861
• Integrated Intel GPUs arelimited due to lack of hwmon interface (it's an issue on intel's side,i915 source,xe source)

• GPU usage requiresecho N | sudo tee /sys/class/drm/renderD*/device/profiling
  • Where N is a number, 1 for panfrost and 3 for panthor.