MangoHud

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, and MANGOHUD_PRESETSFILE
  • Vsync
    • OpenGL Vsync
    • Vulkan Vsync
  • Keybindings
  • Workarounds
  • FPS logging
    • Online visualization: FlightlessMango.com
    • Local visualization: mangoplot
  • Metrics support by GPU vendor/driver

Installation - Build From Source

---

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.git
cd MangoHud

Using meson to install "manually":

meson build
ninja -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 append mangohud to libdir if desired (e.g. /usr/local/lib/mangohud).

To install 32-bit build on 64-bit distro, specify proper libdir: 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 change PKG_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 lib32
ninja -C build32 install

Dependencies

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 with meson to disable
• D-Bus (libdbus-1-dev), optional, use -Dwith_dbus=disabled option with meson to disable
• wayland-client
• xkbcommon

Python 3 libraries:

• Mako (python3-mako or install with pip)

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

Meson options

| Option | Default | Description | -------- | ------- | - | with_nvml | enabled |Required for NVIDIA GPU metrics on wayland | with_xnvctrl | enabled |Required for NVIDIA GPU metrics on older GPUs | with_x11 | enabled |Required for keybinds on x11 | with_wayland | enabled |Required for keybinds on wayland | with_dbus | enabled |Required for using the media features | mangoapp | false |Includes mangoapp | mangohudctl | false |Include mangohudctl | tests | auto |Includes tests | mangoplot | true |Includes mangoplot

Building with build script

You can also use build.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, although package should also call build 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 the build folder, execute:

./build.sh clean

Currently it just does rm -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!

Installation - Pre-packaged Binaries

---

GitHub releases

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

./mangohud-setup.sh install

Arch-based distributions

If you are using an Arch-based distribution, install mangohud and lib32-mangohud from the extra/multilib repository. mangohud-git and lib32-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

Debian, Ubuntu

If you are using Debian 11 (Bullseye) or later, Ubuntu 21.10 (Impish) or later, or distro derived from them, to install the MangoHud 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.

Fedora

If you are using Fedora, to install the MangoHud package, execute:

sudo dnf install mangohud

Solus

If you are using Solus, to install MangoHud simply execute:

sudo eopkg it mangohud

openSUSE

If you run openSUSE Leap or Tumbleweed you can get Mangohud from the official repositories. There are two packages, mangohud for 64bit and mangohud-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.repo
sudo zypper install mangohud

Leap 15.3

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

Flatpak

If you are using Flatpaks, you will have to add the Flathub 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

Normal usage

---

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 the Command prefix setting:

mangohud

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

mangohud %command%

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

OpenGL

OpenGL games may also need dlsym hooking, which is now enabled by default. Set the MANGOHUD_DLSYM env to 0 to disable like MANGOHUD_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 script LD_PRELOAD=/path/to/mangohud/lib/

gamescope

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

Using normal mangohud with gamescope is not supported.

Hud configuration

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 or get 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 executab