I have used GOverlay on Ubuntu to configure MangoHud. Having the settings in a window makes it easier to choose which figures appear on screen, move the overlay, and save a layout without editing every option by hand.
GOverlay is written in Free Pascal using Lazarus and the Qt6 widgetset. This guide covers building it from source, running it locally, and installing it under /usr/local. It also covers an issue I ran into with global MangoHud settings while testing older Wine games.
Updated: 24 October 2026. The latest stable upstream release is GOverlay 1.9.4, published on 10 October 2026. The main walkthrough builds that tagged release; the development branch can contain newer changes.
Build dependencies · Compile GOverlay · Install · Configure MangoHud · Troubleshooting · Other installation methods
What GOverlay configures
GOverlay, developed by Benjamim Gois and contributors, provides a graphical interface for tools used in Linux gaming. MangoHud supplies the performance overlay: FPS, frametimes, temperatures, CPU and GPU information. vkBasalt supplies Vulkan post-processing effects such as sharpening and anti-aliasing.
The current application also includes configuration for vkSumi, OptiScaler, frame-generation tools, and Proton environment settings. Those features depend on the relevant tools and the game’s rendering setup. Building the GOverlay interface does not build every component it can configure.
The 1.1 release introduced Qt6 in March 2024, followed by a 1.1.1 build fix. In May 2026, version 1.8.0 added per-game configuration and a redesigned interface. That is useful when one game needs different settings from the rest of the library.

1. Install the build dependencies
You need Git, Make, Free Pascal, the Lazarus build tools and sources, Qt6 development libraries, and the Qt6 Pascal bindings. MangoHud must also be installed for normal use. The current Makefile selects Qt6 through LAZBUILDOPTS.
Debian 13 / Ubuntu 26.04
These releases provide Lazarus 4.x and Qt6 Pascal development packages. First refresh the package list and check the available versions:
sudo apt update
apt-cache policy lazarus lazarus-src libqt6pas-dev qt6-base-dev
Then install the toolchain, libraries used by the interface and preview, and MangoHud:
sudo apt install build-essential git fpc lazarus lazarus-src \
libqt6pas-dev qt6-base-dev libsdl2-dev libglu1-mesa-dev libx11-dev \
mangohud fontconfig
Ubuntu packages such as Lazarus and libqt6pas-dev are in Universe. If a package has no installation candidate, check the repositories enabled for your Ubuntu release. Older releases can need a newer Lazarus toolchain or Qt6 Pascal bindings; use the Flatpak or AppImage route below if you want to avoid maintaining those yourself.
The Ubuntu 26.04 Lazarus package, Ubuntu Qt6 Pascal package, and Debian 13 Qt6 Pascal package list the relevant distribution versions. A Qt5 Pascal library does not replace the Qt6 library used by this build.
Arch Linux
sudo pacman -Syu --needed base-devel git fpc fpc-src lazarus lazarus-qt6 \
qt6pas qt6-base sdl2-compat glu mangohud fontconfig ttf-nerd-fonts-symbols
Arch provides qt6pas and lazarus-qt6. The full-system upgrade in -Syu keeps the compiler and libraries in step with the rest of the installation.
Optional tools and fonts
Install vkBasalt if you want its post-processing effects, and GameMode if you intend to use the GameMode feature. On Debian or Ubuntu:
sudo apt install vkbasalt gamemode
GOverlay also uses Nerd Fonts for some icons. A missing font can leave squares or missing glyphs in the interface. Install a patched Nerd Font or the Symbols Nerd Font through a suitable package or the font project’s releases.
2. Check that the compiler is available
git --version
make --version
fpc -iV
lazbuild --version
Run the build and application as your normal user. Administrator access is needed for installing system packages and, later, copying the finished application into /usr/local.
3. Clone and compile GOverlay 1.9.4
This creates a separate checkout in ~/src/goverlay-1.9.4. If that directory already exists, use the existing checkout or choose another directory.
mkdir -p "$HOME/src"
git clone --branch 1.9.4 --depth 1 https://github.com/benjamimgois/goverlay.git "$HOME/src/goverlay-1.9.4"
cd "$HOME/src/goverlay-1.9.4"
git describe --tags --always
make
Git checks out the release tag in a detached HEAD state, which is normal for this release build. The make command builds goverlay, the PasCube Vulkan preview, the bgmod launcher helpers, and the splash program. It also creates start_goverlay.sh.
Calling lazbuild on the main project alone only builds that project. The full Makefile is the practical route when you want the accompanying preview and helpers too. It invokes the main build with --bm=Release and --ws=qt6.
If you specifically want development code
Use an unpinned checkout instead of the release checkout above:
git clone https://github.com/benjamimgois/goverlay.git "$HOME/src/goverlay-main"
cd "$HOME/src/goverlay-main"
make
This follows the repository’s main branch. A newly committed change can still have a build or runtime problem, so check the release notes when choosing between a tagged release and development code.
4. Run the local build
From the checkout you just built, run the generated startup script:
./start_goverlay.sh
The project’s contributor instructions use this local launcher. You can also start the compiled program directly with ./goverlay. Keep the checkout’s accompanying files in place while running locally.
Open the MangoHud section, choose a layout, and save it. Use the preview control to check the result. PasCube needs a working Vulkan setup; compiling the GUI successfully and launching the Vulkan preview are separate checks.
5. Install GOverlay system-wide
Close the local application, stay in the same checkout, and install the finished build:
sudo make install
With the Makefile’s default prefix, the launcher goes to /usr/local/bin/goverlay, compiled programs go under /usr/local/libexec, and resources and desktop integration go under /usr/local/share. Launch the installed copy with:
goverlay
If you already had a distribution package installed, check which executable your shell selects:
type -a goverlay
You may see both /usr/local/bin/goverlay and /usr/bin/goverlay. An APT or Pacman update manages the packaged copy; it does not rebuild the source installation in /usr/local.
6. Apply the settings to a game
Saving a configuration and enabling a tool for a game are separate steps. For a simple MangoHud setup in Steam, open the game’s Properties and put this in Launch Options:
mangohud %command%
That uses MangoHud’s normal configuration lookup. When you select a game and create a GOverlay per-game profile, use the launch command GOverlay generates for that profile so it points at the correct configuration files.
For Lutris, use the Lutris instructions in GOverlay’s finish dialog and the matching game configuration. %command% is a Steam launch-options token; it is not a Wine executable or a command to paste unchanged into Lutris.
For vkBasalt, the renderer must use Vulkan. Wine games using DXVK or VKD3D can meet that requirement; a game using WineD3D’s OpenGL path needs a different approach for post-processing. MangoHud supports both Vulkan and OpenGL, but the loading method and available metrics can differ.
Global MangoHud and older Wine games
While testing Code of Honor 2 on Ubuntu, I got it working with DXVK disabled. Turning off GOverlay’s global MangoHud setting also helped, and enabling MangoHud again brought more trouble. I had changed both the renderer and the overlay during those tests.
MangoHud’s no_display option hides the HUD. Hiding it does not unload the overlay from the process. For a useful comparison, turn off global enable, remove any MangoHud launch wrapper or per-game toggle, restart the launcher, and test the game with the same Wine and DXVK settings. Then change one setting at a time.
For older 32-bit games, check the 32-bit overlay support provided by your chosen MangoHud package as well. A working overlay in a 64-bit game does not establish that the 32-bit libraries are present.
7. Update or remove the source installation
For a later stable release, repeat the tagged-checkout build with the new tag shown on the official releases page, run it locally, and install it with sudo make install. Keep the checkout used for installation.
For the separate development checkout, update and rebuild as your normal user:
cd "$HOME/src/goverlay-main"
git pull --ff-only
make clean
make
./start_goverlay.sh
After checking the rebuilt application, close it and run sudo make install again if you want to update the installed copy. Resolve any Git conflict or local-change message before continuing.
To remove a source installation, return to its matching checkout and run:
sudo make uninstall
Use the same prefix as the original installation if you changed it. The uninstall target removes the installed program and shared resources; your per-user configurations and separately installed tools remain. Per-game wrappers or injected components should be removed through the relevant GOverlay game-profile controls before removing the application.
Troubleshooting
Missing lazbuild, FPC, LCL, or a Lazarus package
Check the toolchain commands in step 2. The main project requires LCL and LazOpenGLContext. Install the Lazarus sources and component packages belonging to the same toolchain. A missing Interfaces unit or Qt6 widgetset is a Lazarus/LCL setup issue, rather than a missing MangoHud option.
The linker cannot find Qt6Pas
Check that the Qt6 Pascal development package is installed for your architecture. On Debian and Ubuntu that is libqt6pas-dev; on Arch it is qt6pas. Keep it compatible with the Lazarus and Qt6 versions in use. Use the upstream binding guidance if your distribution does not provide it.
GOverlay opens, but the preview or a game has no overlay
Check MangoHud itself, the game’s graphics API, and whether the application is native or sandboxed. Start the source build from a terminal to retain its error output. For a 32-bit game, also check the matching libraries. A missing Nerd Font affects icons, while a missing Vulkan layer or driver affects the preview or game.
Light-theme buttons or launch paths behave incorrectly
The 1.9.4 release notes include fixes for unreadable controls under some KDE/Kubuntu themes, quoted Lutris paths containing spaces, and Proton launch-argument ordering. Compare your installed version with the release containing the relevant fix before replacing configuration files.
Check an existing Ubuntu installation before replacing it
These commands only inspect the current installation. Run them individually; an absent package or Flatpak application can simply mean you used another installation method.
type -a goverlay
command -v goverlay
dpkg-query -W -f='${Package}\t${Version}\n' goverlay mangohud libqt6pas6 libqt5pas1 2>/dev/null
flatpak info io.github.benjamimgois.goverlay
APT’s retained installation records can help identify an old package installation:
zgrep -hiE 'goverlay|mangohud|libqt.*pas' /var/log/apt/history.log* /var/log/dpkg.log* 2>/dev/null | tail -n 80
Shell history can show commands you ran, but it normally does not retain their error output. Rotated or deleted package logs can also leave gaps. When reporting a current problem, include the GOverlay release or Git commit, distribution, installation method, Lazarus/FPC versions, and the first relevant build error.
Other installation methods
If you want to use GOverlay without maintaining a Pascal toolchain, upstream recommends Flatpak or AppImage for distributions whose packages lag behind. Arch also provides a current native package.
Flatpak
Install Flatpak using the instructions for your distribution, then add Flathub if needed and install GOverlay:
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install flathub io.github.benjamimgois.goverlay
flatpak run io.github.benjamimgois.goverlay
The Flatpak build hides host-dependent GameMode and Protontricks features. A sandboxed GOverlay installation also does not automatically give every host game or launcher a working overlay; follow the instructions for that game’s Steam or Lutris installation.
AppImage or distribution package
Download the AppImage matching your architecture from the release assets. For the 1.9.4 x86-64 file, open a terminal in its download directory and run:
chmod +x goverlay-1.9.4-x86_64.AppImage
./goverlay-1.9.4-x86_64.AppImage
For the distribution-managed application, use the appropriate package command instead of the source-install steps:
sudo apt install goverlay mangohud
sudo pacman -Syu goverlay mangohud
Check the package version first if you need a particular new feature or fix. The application package, its external tools, and their 32-bit components can have different packaging arrangements.
Sources and Linux discussions
- Official GOverlay documentation, 1.9.4 Makefile, and build and contributor instructions
- GOverlay release history and changelogs
- MangoHud: usage, configuration, and library support
- vkBasalt: effects, requirements, and configuration
- Ubuntu Lazarus packages, Debian Lazarus packages, and Arch GOverlay package information
- DanishFurryGame Steam group
