# Compile and Install GOverlay on Linux: 2026 Guide

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

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](https://github.com/benjamimgois/goverlay/releases/tag/1.9.4).
The main walkthrough builds that tagged release; the development branch can contain
newer changes.

[Build dependencies](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-goverlay-on-linux-2026-guide/#dependencies)·
[Compile GOverlay](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-goverlay-on-linux-2026-guide/#build)·
[Install](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-goverlay-on-linux-2026-guide/#install)·
[Configure MangoHud](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-goverlay-on-linux-2026-guide/#configuration)·
[Troubleshooting](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-goverlay-on-linux-2026-guide/#troubleshooting)·
[Other installation methods](https://wordpress.theicealphawolfden.com/index.php/2026/10/24/compile-and-install-goverlay-on-linux-2026-guide/#alternatives)

## What GOverlay configures

[GOverlay](https://github.com/benjamimgois/goverlay), developed by Benjamim Gois
and contributors, provides a graphical interface for tools used in Linux gaming.
[MangoHud](https://github.com/flightlessmango/MangoHud) supplies the performance
overlay: FPS, frametimes, temperatures, CPU and GPU information. [vkBasalt](https://github.com/DadSchoorse/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](https://github.com/benjamimgois/goverlay/releases/tag/1.1),
followed by a [1.1.1 build fix](https://github.com/benjamimgois/goverlay/releases/tag/1.1.1).
In May 2026, [version 1.8.0 added per-game configuration and a redesigned interface](https://github.com/benjamimgois/goverlay/releases/tag/1.8.0).
That is useful when one game needs different settings from the rest of the library.

[⌊GOverlay 1.8.3 showing MangoHud layout presets and colour themes, with the Global
config indicator visible.⌉⌊GOverlay 1.8.3 showing MangoHud layout presets and colour
themes, with the Global config indicator visible.⌉[

Official GOverlay 1.8.3 screenshot showing MangoHud presets and colour themes. Image:
Benjamim Gois and GOverlay contributors; [upstream source](https://github.com/benjamimgois/goverlay/blob/1.9.4/data/screenshots/2.webp)
and [project licence](https://github.com/benjamimgois/goverlay/blob/1.9.4/LICENSE).
The build instructions below target 1.9.4.

## 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](https://github.com/benjamimgois/goverlay/blob/1.9.4/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:

    ```wp-block-code
    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:

    ```wp-block-code
    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](https://packages.ubuntu.com/resolute/lazarus),
[Ubuntu Qt6 Pascal package](https://packages.ubuntu.com/resolute/libqt6pas-dev),
and [Debian 13 Qt6 Pascal package](https://packages.debian.org/trixie/libqt6pas-dev)
list the relevant distribution versions. A Qt5 Pascal library does not replace the
Qt6 library used by this build.

### Arch Linux

    ```wp-block-code
    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](https://archlinux.org/packages/extra/x86_64/qt6pas/) and 
[lazarus-qt6](https://archlinux.org/packages/extra/x86_64/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:

    ```wp-block-code
    sudo apt install vkbasalt gamemode
    ```

GOverlay also uses [Nerd Fonts](https://github.com/ryanoasis/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

    ```wp-block-code
    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.

    ```wp-block-code
    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:

    ```wp-block-code
    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:

    ```wp-block-code
    ./start_goverlay.sh
    ```

The [project’s contributor instructions](https://github.com/benjamimgois/goverlay/blob/1.9.4/CONTRIBUTING.md)
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:

    ```wp-block-code
    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:

    ```wp-block-code
    goverlay
    ```

If you already had a distribution package installed, check which executable your
shell selects:

    ```wp-block-code
    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:

    ```wp-block-code
    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](https://github.com/benjamimgois/goverlay/releases),
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:

    ```wp-block-code
    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:

    ```wp-block-code
    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](https://github.com/benjamimgois/goverlay/blob/1.9.4/README.md#libqt6pas)
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.

    ```wp-block-code
    type -a goverlay
    command -v goverlay
    ```

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

    ```wp-block-code
    flatpak info io.github.benjamimgois.goverlay
    ```

APT’s retained installation records can help identify an old package installation:

    ```wp-block-code
    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](https://flatpak.org/setup/),
then add Flathub if needed and install GOverlay:

    ```wp-block-code
    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](https://github.com/benjamimgois/goverlay/releases/tag/1.9.4).
For the 1.9.4 x86-64 file, open a terminal in its download directory and run:

    ```wp-block-code
    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:

    ```wp-block-code
    sudo apt install goverlay mangohud
    ```

    ```wp-block-code
    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](https://github.com/benjamimgois/goverlay/blob/1.9.4/README.md),
   [1.9.4 Makefile](https://github.com/benjamimgois/goverlay/blob/1.9.4/Makefile),
   and [build and contributor instructions](https://github.com/benjamimgois/goverlay/blob/1.9.4/CONTRIBUTING.md)
 * [GOverlay release history and changelogs](https://github.com/benjamimgois/goverlay/releases)
 * [MangoHud: usage, configuration, and library support](https://github.com/flightlessmango/MangoHud)
 * [vkBasalt: effects, requirements, and configuration](https://github.com/DadSchoorse/vkBasalt)
 * [Ubuntu Lazarus packages](https://packages.ubuntu.com/resolute/lazarus), [Debian Lazarus packages](https://packages.debian.org/trixie/lazarus),
   and [Arch GOverlay package information](https://archlinux.org/packages/extra/x86_64/goverlay/)
 * [DanishFurryGame Steam group](https://steamcommunity.com/groups/DanishFurryGameFan)
