# Compile and Install MangoHud from Source on Linux: 2026 Guide

- Link: https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/
- Published: 2026-10-24T20:39:02+02:00
- Author: Kiba Snowpaw

I had both 32-bit and 64-bit MangoHud libraries on my Ubuntu system when I was troubleshooting
_Furry College_ through Proton. The log still produced `wrong ELF class` warnings.
Having the files on disk was only one part of getting the overlay to load into the
right process.

This guide covers building MangoHud from its official source, installing the 64-
bit overlay, adding 32-bit support on Debian or Ubuntu, and building MangoApp for
Gamescope. The commands target an **x86-64 Linux system**.

**Updated: 24 October 2026.** The latest stable upstream release is [MangoHud 0.8.4, released on 27 May 2026](https://github.com/flightlessmango/MangoHud/releases/tag/v0.8.4).
I use that tag for the main walkthrough. Its build requires Meson 0.60 or newer 
and C++17; the current development branch already requires Meson 1.7 and C++20, 
along with additional dependencies.

[Before installing](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/#prepare)·
[Dependencies](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/#dependencies)·
[Build MangoHud](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/#build)·
[32-bit support](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/#32-bit)·
[Steam and Lutris](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/#using)·
[MangoApp](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/#mangoapp)·
[Troubleshooting](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-mangohud-from-source-on-linux-2026-guide/#troubleshooting)

## What MangoHud does

[MangoHud](https://github.com/flightlessmango/MangoHud) is an overlay for Vulkan
and OpenGL applications. It can display FPS, frametimes, CPU and GPU load, memory
use, temperatures and other supported readings. It also provides logging and frame-
limiting options. The available hardware readings depend on the GPU, driver and 
monitoring interfaces.

FlightlessMango released [version 0.1.0 in February 2020](https://github.com/flightlessmango/MangoHud/releases/tag/v0.1.0),
building on the Mesa Vulkan overlay. [Version 0.3.0 added OpenGL support in March 2020](https://github.com/flightlessmango/MangoHud/releases/tag/v0.3.0).
The 0.8.4 release includes fixes for Steam Overlay coexistence and Vulkan loader
forwarding.

[⌊Official animated MangoHud example showing GPU and CPU readings, memory usage,
FPS and a frametime graph.⌉⌊Official animated MangoHud example showing GPU and CPU
readings, memory usage, FPS and a frametime graph.⌉[

Upstream’s animated overlay example, showing FPS, frametimes and hardware readings.
Image: FlightlessMango and MangoHud contributors. [Original asset](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/assets/overlay_example.gif)·
[project licence](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/LICENSE).

## 1. Check the existing installation

Choose one installation method before copying files onto the system. A distribution
package, the upstream build script and a manual Meson installation can put MangoHud
in different places. Multiple Vulkan manifests or an old launcher can make troubleshooting
harder.

    ```wp-block-code
    type -a mangohud
    command -v mangoapp
    uname -m
    ```

On Debian or Ubuntu, check the package manager too:

    ```wp-block-code
    dpkg-query -W -f='${Package}\t${Version}\n' mangohud mangoapp 2>/dev/null
    ```

The manual build below installs under `/usr/local`. The upstream helper script installs
under `/usr` and removes matching files there before copying its build. If you are
switching installation methods, remove the previous installation through the method
that owns it. Keeping two copies in different prefixes does not guarantee that only
one Vulkan layer will be discovered.

## 2. Install the build dependencies

Run the package block for your distribution. These are development dependencies 
for the tagged 0.8.4 build. They are separate from the graphics driver needed to
run the overlay.

### Debian / Ubuntu

    ```wp-block-code
    sudo apt update
    sudo apt install build-essential git meson ninja-build pkg-config python3-mako \
      glslang-tools libgl-dev libegl-dev libx11-dev libxnvctrl-dev \
      libdbus-1-dev libwayland-dev libxkbcommon-dev file
    ```

### Fedora

    ```wp-block-code
    sudo dnf install git gcc gcc-c++ meson ninja-build pkgconf-pkg-config \
      python3-mako glslang mesa-libGL-devel mesa-libEGL-devel libX11-devel \
      libXNVCtrl-devel dbus-devel wayland-devel libxkbcommon-devel file
    ```

### Arch / Manjaro

    ```wp-block-code
    sudo pacman -Syu --needed base-devel git meson ninja pkgconf python-mako \
      glslang libglvnd libx11 libxnvctrl dbus wayland libxkbcommon file
    ```

Check the tools before cloning:

    ```wp-block-code
    meson --version
    ninja --version
    g++ --version
    python3 -c "import mako; print(mako.__version__)"
    ```

If a dependency is missing, use the first relevant Meson error to identify it. Read
the requirements from the same source tag you are building. The development branch’s
dependency list can differ substantially from a stable release.

## 3. Clone the stable source

This creates a fresh checkout at `~/src/MangoHud-0.8.4`. Use another directory if
that one already exists.

    ```wp-block-code
    mkdir -p "$HOME/src"
    git clone --branch v0.8.4 --recurse-submodules https://github.com/flightlessmango/MangoHud.git "$HOME/src/MangoHud-0.8.4"
    cd "$HOME/src/MangoHud-0.8.4"
    git describe --tags --always
    git submodule update --init --recursive
    ```

Checking out a tag leaves Git in a detached HEAD state. That is normal for building
a specific release. Meson can also fetch dependency sources declared in the project’s`
subprojects` directory during configuration.

## 4. Configure, compile and install the 64-bit build

Run **one** configuration block below, matching your distribution. Each uses a library
directory appropriate to its x86-64 layout. The `mangohud` launcher uses the dynamic
linker’s architecture-dependent library token when loading the OpenGL shim.

### Debian / Ubuntu

    ```wp-block-code
    CC=gcc CXX=g++ meson setup build64 --prefix=/usr/local \
      --libdir=lib/x86_64-linux-gnu --buildtype=release -Dmangoplot=disabled
    ```

### Fedora

    ```wp-block-code
    CC=gcc CXX=g++ meson setup build64 --prefix=/usr/local \
      --libdir=lib64 --buildtype=release -Dmangoplot=disabled
    ```

### Arch / Manjaro

    ```wp-block-code
    CC=gcc CXX=g++ meson setup build64 --prefix=/usr/local \
      --libdir=lib --buildtype=release -Dmangoplot=disabled
    ```

Then compile as your normal user and inspect the resulting OpenGL library:

    ```wp-block-code
    meson compile -C build64
    file build64/src/libMangoHud_opengl.so
    ```

For this build, `file` should identify an ELF 64-bit shared object. Install the 
finished files:

    ```wp-block-code
    sudo meson install -C build64 --no-rebuild
    ```

The `--no-rebuild` option keeps this step to installation after the normal-user 
compile. The launcher is installed as `/usr/local/bin/mangohud`; Vulkan manifests
go under `/usr/local/share/vulkan/implicit_layer.d`. Keep this build directory and
its installation log for updates or removal.

    ```wp-block-code
    hash -r
    type -a mangohud
    mangohud --version
    ```

This walkthrough disables `mangoplot`, the optional plotting helper. The regular
overlay and logging remain available. If you want the plotting helper later, install
its Python requirements, including NumPy and Matplotlib, and enable its Meson option.

## 5. Add 32-bit support on Debian or Ubuntu

A 64-bit operating system can run a 32-bit game, but the process still needs 32-
bit overlay libraries. For an amd64 Debian or Ubuntu installation, enable i386 package
support and install the matching development libraries:

    ```wp-block-code
    sudo dpkg --add-architecture i386
    sudo apt update
    sudo apt install gcc-multilib g++-multilib libgl-dev:i386 libegl-dev:i386 \
      libx11-dev:i386 libdbus-1-dev:i386 libwayland-dev:i386 libxkbcommon-dev:i386
    ```

From the same MangoHud checkout, create a separate build directory:

    ```wp-block-code
    CC="gcc -m32" CXX="g++ -m32" \
    PKG_CONFIG_PATH= \
    PKG_CONFIG_LIBDIR="/usr/lib/i386-linux-gnu/pkgconfig:/usr/share/pkgconfig" \
    meson setup build32 --prefix=/usr/local --libdir=lib/i386-linux-gnu \
      --buildtype=release -Dmangoplot=disabled -Dinclude_doc=false
    meson compile -C build32
    file build32/src/libMangoHud_opengl.so
    ```

This time the library should be an ELF 32-bit shared object. Install the runtime
files only, preserving the 64-bit installation’s shared launcher and documentation:

    ```wp-block-code
    sudo meson install -C build32 --no-rebuild --tags runtime
    ```

The 32-bit libraries and their Vulkan manifest have separate paths. Keep both builds
on the same MangoHud release. On Arch, the corresponding 32-bit library directory
is normally `lib32`; on Fedora it is normally `lib`, with matching multilib development
packages required.

Debian offers a `mangohud:i386` package. The [Ubuntu package listing](https://packages.ubuntu.com/resolute/mangohud)
does not include i386, which is why installing Ubuntu’s ordinary `mangohud` package
is not a substitute for this 32-bit source build.

## 6. Test Vulkan and OpenGL separately

Use a small native application to check each graphics API before testing a complicated
Wine or Proton launch chain. On Debian or Ubuntu, the test programs are available
with:

    ```wp-block-code
    sudo apt install mesa-utils vulkan-tools
    ```

With `glxgears` and `vkcube` installed, run them separately:

    ```wp-block-code
    mangohud glxgears
    ```

    ```wp-block-code
    mangohud vkcube
    ```

These check your native 64-bit setup. A working result does not test a 32-bit game
or every Steam runtime. In 0.8.4, dlsym hooking is already enabled by default; the
launcher retains `--dlsym` as a compatibility option.

### Steam

For an individual game, open Properties → Launch Options and enter:

    ```wp-block-code
    mangohud %command%
    ```

For a Vulkan-only test, this enables the layer through its environment setting:

    ```wp-block-code
    MANGOHUD=1 %command%
    ```

For OpenGL, use the `mangohud` wrapper so the preload mechanism is configured. `
MANGOHUD=1` alone is not the equivalent OpenGL setup.

### Lutris

Open the game’s configuration and find System options → Command prefix, enabling
advanced options if needed. Add:

    ```wp-block-code
    mangohud
    ```

If Lutris already enables MangoHud through its own toggle, use that route instead
of adding a second prefix. A GOverlay-generated per-game command can also point 
at a specific configuration. Use the command intended for Lutris; `%command%` belongs
to Steam launch options.

## 7. Build MangoApp for Gamescope

During my _Code of Honor 2_ testing on 7 May 2026, Gamescope repeatedly reported:

    ```wp-block-code
    Failed to start process "mangoapp": No such file or directory
    ```

MangoApp is a separate executable used for the Gamescope overlay. The [0.8.4 source options](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/meson_options.txt)
set `mangoapp` to `false` by default, so installed MangoHud libraries do not guarantee
that this executable exists.

Install the GLFW development package for your distribution: `libglfw3-dev` on Debian/
Ubuntu, `glfw-devel` on Fedora, or the appropriate `glfw` package on Arch. For Debian
or Ubuntu:

    ```wp-block-code
    sudo apt install libglfw3-dev
    ```

Enable MangoApp in the existing native 64-bit build, compile it, and install the
updated native build:

    ```wp-block-code
    meson configure build64 -Dmangoapp=true
    meson compile -C build64
    sudo meson install -C build64 --no-rebuild
    command -v mangoapp
    ```

This uses the manual Meson installation. In 0.8.4, the helper script’s installation
file list does not copy `mangoapp`, even if it was compiled. For a Steam game running
through Gamescope, upstream documents:

    ```wp-block-code
    gamescope --mangoapp -- %command%
    ```

Use MangoApp for that Gamescope setup. Upstream does not support wrapping Gamescope
with the ordinary MangoHud overlay.

## The build.sh route and optional packaging

The repository also includes the helper used in many older MangoHud instructions.
Use it as an alternative installation route, rather than mixing it with the Meson
installation above:

    ```wp-block-code
    ./build.sh build
    ./build.sh install
    ```

On x86-64 it configures both native and 32-bit builds, stages files under `build/
release`, and uses administrator access for dependency changes and installation.
Its Debian/Ubuntu dependency handling can enable i386 and, in the 0.8.4 script, 
download a glslang binary. Review those operations before choosing this route.

Packaging is optional for installing on the same machine. To create the helper’s
archive containing an installer, use:

    ```wp-block-code
    ./build.sh package release
    ```

The `package` step creates `build/MangoHud-package.tar`; `release` creates a versioned
compressed archive containing `mangohud-setup.sh`. This is an upstream installation
archive, not a distribution-managed DEB or RPM package.

## Troubleshooting the problems I encountered

### wrong ELF class: ELFCLASS64 or ELFCLASS32

My 30 December 2025 _Furry College_ logs, using GE-Proton10-27, contained both kinds
of preload warning. Libraries were present in 32-bit and 64-bit locations, but a
preload request could reach processes with a different architecture.

| Warning | What it means for that load attempt | 
| `ELFCLASS64` | A 32-bit loader was offered a 64-bit ELF library. | 
| `ELFCLASS32` | A 64-bit loader was offered a 32-bit ELF library. |

Steam and Wine can launch helpers of different architectures. Identify which process
and library the message refers to; a warning from one helper does not identify the
architecture of every process or establish the cause of a game crash.

Check the relevant library with `file`. For the two Debian/Ubuntu builds in this
guide:

    ```wp-block-code
    file /usr/local/lib/x86_64-linux-gnu/mangohud/libMangoHud_opengl.so \
         /usr/local/lib/i386-linux-gnu/mangohud/libMangoHud_opengl.so
    ```

Start with the installed `mangohud` wrapper. Hard-coding a single 32-bit or 64-bit
OpenGL library into a launcher-wide `LD_PRELOAD` can send it into processes it cannot
load into.

### MangoHud appears without a per-game request

Inspect the environment inherited by the launcher:

    ```wp-block-code
    env | grep -E '^(MANGOHUD[^=]*|DISABLE_MANGOHUD|LD_PRELOAD|VK_INSTANCE_LAYERS)='
    ```

The normal wrapper itself sets `MANGOHUD=1` and adds an OpenGL shim to `LD_PRELOAD`.
A path such as `/usr/local/$LIB/mangohud/libMangoHud_shim.so` uses a token expanded
by the dynamic linker. Seeing that path in a launched process does not, by itself,
show where a global setting was enabled.

Check GOverlay’s global option, Lutris’s MangoHud toggle and command prefix, Steam
launch options, and any session-wide environment setting. Restart the launcher after
changing inherited settings. MangoHud’s `no_display` option hides the HUD while 
leaving it loaded.

With _Code of Honor 2_, I got the game working with DXVK disabled; turning off global
MangoHud also helped, and re-enabling MangoHud caused more trouble. Keep the renderer
fixed while comparing the overlay on and off, then test DXVK separately.

### Multiple installed copies and ldconfig output

Check the launcher path and look for libraries or older copies under both system
prefixes:

    ```wp-block-code
    type -a mangohud
    find /usr/lib /usr/lib64 /usr/local/lib /usr/local/lib64 \
      \( -iname "*mangohud*" -o -iname "*mangoapp*" \) -print 2>/dev/null
    ```

A source build or staging directory is not automatically the copy loaded by the 
game. An empty `ldconfig -p` search also does not establish that MangoHud is missing:
its Vulkan manifest and launcher can reference libraries by path.

### Launch-wrapper errors and other log messages

An `env: … No such file or directory` error referring to a Steam launch wrapper 
needs its command, quoting and executable path checked. It does not identify a failed
MangoHud compile. Likewise, an unavailable battery reading or CPU power sensor can
explain a missing metric without explaining a game crash.

For a build failure, keep the first actual compiler or Meson error. For a runtime
problem, record the MangoHud version, game, graphics API, process architecture, 
Wine/Proton version and installation method.

## Update or uninstall the source build

For a later stable version, use its release tag in a fresh checkout, read its matching
requirements, and rebuild the architectures you need. The current development branch
is `master`; cloning it without a tag can require newer compilers and libraries 
than the 0.8.4 commands above.

For the manual installation, keep the build directories and use their uninstall 
targets. Remove the optional 32-bit build first if you installed it, followed by
the native build:

    ```wp-block-code
    sudo ninja -C build32 uninstall
    sudo ninja -C build64 uninstall
    ```

For a helper-script installation, use `./build.sh uninstall` from its checkout. 
Do not use that helper to remove the separate `/usr/local` Meson installation.

## Distribution packages and Flatpak

If you do not need to build source, the distribution package is easier to maintain.
Debian provides 32-bit MangoHud packages; Arch provides `mangohud` and `lib32-mangohud`.
Check the package version and architecture support for your distribution.

A host installation also does not automatically install MangoHud inside Flatpak 
Steam. Use the [upstream Flatpak instructions](https://github.com/flightlessmango/MangoHud#flatpak)
and [MangoHud extension documentation](https://github.com/flathub/org.freedesktop.Platform.VulkanLayer.MangoHud),
choosing the extension branch that matches the application’s runtime.

## References

 * [MangoHud 0.8.4 README](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/README.md)
   and [official release history](https://github.com/flightlessmango/MangoHud/releases)
 * [Tagged build requirements](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/meson.build),
   [Meson options](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/meson_options.txt),
   and [library, launcher and MangoApp installation rules](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/src/meson.build)
 * [Upstream build script](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/build.sh)
   and [its dependency lists](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/build_deps.sh)
 * [MangoHud launcher implementation](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/bin/mangohud.in)
   and [Vulkan layer manifest](https://github.com/flightlessmango/MangoHud/blob/v0.8.4/src/mangohud.json.in)
 * [Meson installation and install tags](https://mesonbuild.com/Installing.html)·
   [Linux dynamic-linker documentation](https://man7.org/linux/man-pages/man8/ld.so.8.html)
 * [Ubuntu](https://packages.ubuntu.com/resolute/mangohud), [Debian](https://packages.debian.org/trixie/mangohud),
   [Fedora](https://packages.fedoraproject.org/pkgs/mangohud/mangohud/), and [Arch package information](https://archlinux.org/packages/extra/x86_64/mangohud/)
