The missing frame rate overlay
You fire up a demanding title on Fedora and the frame pacing feels uneven. You suspect a thermal throttle, a driver bottleneck, or a background process stealing cycles, but guessing is useless. You need real-time telemetry: frames per second, GPU temperature, CPU utilization, and VRAM consumption. MangoHud delivers exactly that, but the first time you run it, the overlay either vanishes completely or throws a Vulkan layer registration error. The tool works by injecting itself into the game process, which means it depends on your graphics stack, your sandbox boundaries, and your environment variables. Get those three pieces aligned and the overlay stays put.
How the overlay actually works
MangoHud does not run as a background daemon. It relies on dynamic library injection using the LD_PRELOAD mechanism. When you prefix a command with mangohud, the wrapper sets environment variables that force the dynamic linker to load libMangoHud.so before the game starts. That shared library intercepts OpenGL and Vulkan API calls, hooks into the rendering pipeline, and polls hardware telemetry from the kernel. The library then draws a text overlay directly onto the frame buffer before the final image reaches the compositor.
Because the injection happens at the process level, MangoHud only works when the game actually uses the system graphics stack. Flatpak sandboxes isolate applications from host libraries. Wayland compositors handle surface rendering differently than X11. Missing Vulkan layers or mismatched Mesa versions will break the injection silently. The overlay disappears not because the tool is broken, but because the dynamic linker cannot find the shared library or the game refuses to load it. Understanding that chain of dependencies makes troubleshooting straightforward.
Run ldd on the MangoHud library before you launch a game. Half the time the missing dependency is a Vulkan ICD or a GLVND component.
Install and run the wrapper
Fedora ships a stable MangoHud package in the main repositories. The version tracks closely with upstream releases and receives security patches through the normal update cycle. If you need experimental features or a specific bug fix that has not yet landed in the stable branch, you can enable the official COPR repository. COPR packages are built from the same source tree but track the development branch more aggressively.
Here is how to install the stable version from the main repositories.
sudo dnf install mangohud
# --refresh forces dnf to check for newer metadata before resolving dependencies
# This prevents stale cache issues on systems that rarely run dnf upgrade --refresh
If the main repository version lacks a feature you need, enable the COPR repository and reinstall.
sudo dnf copr enable @mangohud/mangohud
# COPR adds a new repo file to /etc/yum.repos.d/ with a higher priority for this package
sudo dnf install mangohud
# Reinstalling pulls the COPR build and replaces the main repo version cleanly
Once installed, you launch any native Linux game by prefixing the executable with mangohud. The wrapper handles the environment variables and library injection automatically. Steam users can add mangohud %command% to the launch options in the game properties. The %command% placeholder expands to the actual executable path, so the wrapper stays attached regardless of how Steam resolves the binary.
Here is how to run a native executable with custom overlay positioning.
mangohud --fps 120 --fps_pos top_left /usr/bin/your-game-executable
# --fps caps the displayed refresh rate for the FPS counter to reduce visual jitter
# --fps_pos moves the overlay to the top left corner instead of the default bottom left
# The wrapper sets LD_PRELOAD and MANGOHUD=1 before execve() replaces the shell process
Keep the wrapper command simple. Complex shell expansions inside Steam launch options often break the injection chain.
Configure the metrics permanently
Typing flags every time you launch a game defeats the purpose of a persistent overlay. MangoHud reads a configuration file from ~/.config/MangoHud/MangoHud.conf. The file uses a simple key-value format. Each line controls a specific metric, display property, or polling interval. The configuration directory lives in your home folder, which means it survives system upgrades and does not interfere with other user accounts.
Here is how to create the directory and open the configuration file.
mkdir -p ~/.config/MangoHud
# -p creates parent directories if they do not exist and exits silently if the path is already present
nano ~/.config/MangoHud/MangoHud.conf
# Nano opens the file in the terminal. Use Ctrl+O to save and Ctrl+X to exit.
Add your desired settings to the file. A practical configuration for monitoring FPS, CPU, and GPU usage looks like this.
fps=120
# Sets the FPS counter refresh rate. Higher values show more precise frame times but increase CPU overhead.
cpu_temp=1
# Enables CPU temperature polling. Requires coretemp or k10temp kernel modules to be loaded.
gpu_temp=1
# Enables GPU temperature polling. Reads from hwmon sysfs nodes exposed by your driver.
cpu_usage=1
# Shows per-core and aggregate CPU utilization. Useful for identifying single-thread bottlenecks.
gpu_usage=1
# Displays GPU compute and render queue utilization. Helps distinguish driver stalls from hardware limits.
gpu_memory=1
# Shows VRAM allocation and free memory. Critical for tracking texture streaming and asset loading.
fps_pos=top_left
# Moves the overlay to the top left corner. Prevents overlap with in-game HUD elements.
font_size=24
# Increases the overlay text size. Improves readability on high-DPI displays without scaling.
Save the file and launch your game normally. MangoHud reads the configuration on startup and applies the metrics automatically. You do not need to pass command-line flags unless you want to override a specific setting for a single session.
Edit ~/.config/ files, never /usr/lib/ or /etc/ files that ship with the package. User configuration drifts, package files get overwritten on update.
Verify the injection
The overlay should appear immediately after the game initializes its graphics context. If it does not, check whether the environment variables are actually set. MangoHud requires MANGOHUD=1 and LD_PRELOAD pointing to the correct shared library. You can verify the injection by running a lightweight Vulkan test program.
Here is how to confirm the Vulkan layer is registered and the library loads correctly.
MANGOHUD=1 mangohud vulkaninfo --summary
# vulkaninfo queries the Vulkan ICD and prints device capabilities
# The wrapper injects libMangoHud.so into the vulkaninfo process for testing
# If the overlay appears here, the injection chain is working correctly
If the overlay appears in vulkaninfo but not in your game, the game likely uses a different graphics API or bypasses the standard loader. Some titles ship their own Vulkan loader or use proprietary rendering paths. Check the game logs for layer registration warnings.
Run journalctl -xe after a failed launch. Read the actual error before guessing.
Common pitfalls and error patterns
Flatpak sandboxes isolate applications from host libraries by design. The native dnf installation of MangoHud lives outside the sandbox, so Flatpak games cannot see it. You must install the Flatpak version of MangoHud or use the Flatpak override system to inject the host library. The override method is cleaner because it avoids duplicating the package inside the sandbox.
Here is how to grant a Flatpak game access to the host MangoHud library.
flatpak override --user --env=MANGOHUD=1 com.valvesoftware.Steam
# --user applies the override to your account only
# --env sets an environment variable inside the Flatpak runtime before the app starts
# This tells the Steam client to enable MangoHud for all launched titles
Wayland compositors handle surface rendering differently than X11. MangoHud draws directly to the application surface, which means the overlay appears inside the game window. Some Wayland compositors apply color management or HDR tone mapping that shifts the overlay colors. The overlay remains functional, but the contrast may look washed out. Adjust the font_color and background_alpha settings in the configuration file to compensate.
SELinux denials are rare with MangoHud because the tool only reads standard sysfs and procfs paths. If you run custom launch scripts or modify library paths, the security policy may block the injection. Check the audit log for denials before disabling the policy.
Here is how to search for SELinux denials related to MangoHud.
sudo ausearch -m avc -ts recent | grep mangohud
# -m avc filters for access vector cache denials
# -ts recent limits the search to the current boot session
# grep narrows the output to MangoHud-related processes
If you see denials, restore the default context or create a targeted policy. Standard installations work out of the box. Driver mismatches cause more issues than security policies. Keep your Mesa stack updated to prevent rendering glitches in the overlay.
Run sudo dnf upgrade --refresh weekly. Trust the package manager. Manual file edits drift, snapshots stay.
Choose the right monitoring tool
Use MangoHud when you need a lightweight, process-level overlay that shows FPS, temperatures, and utilization without recording video. Use GameMode when you want automatic CPU governor switching, CPU isolation, and background process throttling during gameplay. Use in-game overlays when the title provides built-in telemetry that integrates with the rendering pipeline and respects the game's UI scaling. Use OBS when you need to record gameplay, stream to a platform, or capture system metrics alongside video output. Stay on the native dnf installation if you only deviate from the defaults occasionally.