How can I launch a game with MangoHud enabled?

MangoHud is a powerful performance overlay designed for Linux users, providing real-time metrics such as FPS, CPU/GPU usage, frame times, and temperatures. Whether you’re benchmarking, troubleshooting, or simply curious about your system’s behavior during gameplay, enabling MangoHud allows you to visualize these details with ease and precision.

Launching a game with MangoHud is a straightforward process, compatible with both native Linux titles and games running through Steam, Proton, or Wine. This guide will walk you through various methods to activate MangoHud, ensuring optimal integration regardless of the platform or launcher you’re using.

Launching via Terminal

Basic Command Format

For users running games outside of Steam or other game clients, MangoHud can be launched directly from the Linux terminal. This method is straightforward and particularly effective for standalone games or custom game builds. The basic syntax is:

mangohud /path/to/game

This command invokes MangoHud and attaches the overlay to the specified application. It works by preloading the MangoHud shared library into the application’s runtime environment, enabling real-time metric display as the game runs.

Use Case

This method is ideal for non-Steam games, emulators, or applications that are not tied to any launcher. It is also useful for developers testing performance in applications under development. By bypassing third-party clients, the user maintains full control over the launch environment, ensuring compatibility and reducing variables that might interfere with the overlay.

2. Launching with Steam Games

Setting Launch Options

Steam users can easily enable MangoHud by modifying the launch options of their games. To do this:

• Open Steam and navigate to your Library.
• Right-click on the game you wish to monitor.
• Select ‘Properties’.
• Under the ‘Launch Options’ field, enter the following:

mangohud %command%

This instructs Steam to prepend MangoHud to the default game launch command.

Result

When the game is launched, MangoHud is automatically activated, and performance statistics will be visible on the screen. The overlay typically appears in the top-left corner but can be repositioned through configuration. This integration is reliable and effective for the majority of games distributed through the Steam platform.

Using MangoHud with Proton or Wine

Many Linux gamers use Wine or Proton to run Windows-based games. MangoHud supports both environments, though the setup process includes additional considerations to ensure compatibility.

Proton (Steam)

To use MangoHud with a game running under Proton in Steam:

• Ensure MangoHud is properly installed on your system.
• Open the Steam Library, right-click on the game, and go to ‘Properties’.
• In the ‘Launch Options’, enter:

mangohud %command%

• Confirm that the game is using a Proton version that supports Vulkan or DXVK. These APIs are essential for MangoHud to hook into the rendering pipeline.

This configuration will activate MangoHud during game launch, allowing you to monitor performance even in games designed for Windows.

Wine / Lutris

Wine users can activate MangoHud by exporting an environment variable before launching the game. The process is as follows:

export MANGOHUD=1
wine yourgame.exe

This command ensures that MangoHud hooks into Wine’s rendering system. As long as the game is using Vulkan or OpenGL through DXVK or other wrappers, the overlay should appear.

Lutris-specific

For games managed through Lutris, MangoHud can be enabled via the graphical interface:

• Open Lutris and select the game.
• Click on the configuration icon (usually a gear symbol).
• Go to the ‘Runner Options’ tab.
• Find the setting labeled ‘Enable MangoHud’ and toggle it on.

Lutris will handle the necessary environment setup automatically during game launch.

Verifying That MangoHud Is Active

Once a game is launched, it’s important to verify that MangoHud is working as expected.

• The default overlay appears in the top-left corner of the screen and displays various performance statistics.
• If the overlay does not appear:
  • Confirm the game uses Vulkan or OpenGL. MangoHud does not support DirectX natively unless wrapped via DXVK or similar tools.
  • Try using the --dlsym hook in the launch command:

mangohud --dlsym /path/to/game

• Ensure there are no conflicting overlays or modifications (such as Steam’s own FPS counter or third-party overlays).
• Double-check that MangoHud is properly installed and that no errors were encountered during setup.

Optional: Toggling and Configuring Overlay

MangoHud offers real-time toggling and customization through hotkeys and configuration files.

Hotkeys

• Shift + F12 – Toggle overlay visibility on and off.
• Shift + F11 – Change overlay position.
• Shift + F10 – Cycle through different configuration presets.
• Shift + F4 – Reload configuration file on the fly.

These hotkeys provide convenient ways to manage the overlay without exiting the game.

Configuration File

MangoHud settings can be fine-tuned using a configuration file typically located at:

~/.config/MangoHud/MangoHud.conf

In this file, users can:

• Select which metrics to display (e.g., CPU, GPU, RAM).
• Change text size, color, alignment, and font.
• Enable or disable graphs for frame times or CPU usage.
• Set logging behavior and output directories.

This allows for a highly personalized HUD experience that matches the user’s preferences and system setup.

Troubleshooting Tips

Despite MangoHud’s versatility, users may occasionally encounter issues. The following troubleshooting steps address the most common problems:

• Ensure Graphics API Compatibility: Verify the game uses Vulkan or OpenGL. MangoHud will not display in DirectX environments unless wrapped through Vulkan-compatible layers like DXVK.
• Use the –dlsym Hook: Some games require a special preload flag:

mangohud --dlsym /path/to/game

This forces the application to use dynamic symbol resolution, improving compatibility.

• Check Driver Support: Outdated or misconfigured GPU drivers may prevent MangoHud from functioning. Make sure your graphics drivers are current and properly installed.
• Update MangoHud: Newer versions often fix compatibility issues. Reinstall or update MangoHud if the overlay fails to load.
• Avoid Conflicts: Disable other overlays, injectors, or launch scripts that may override environment variables.

Conclusion

MangoHud is a powerful, flexible, and efficient solution for real-time performance monitoring on Linux systems. Whether you’re launching a standalone game from the terminal, integrating with Steam, or running a title through Proton or Lutris, MangoHud can be seamlessly incorporated into your workflow.

This guide has covered multiple methods for enabling MangoHud, from basic terminal commands to advanced configuration and troubleshooting. With just a few simple commands or tweaks, you can gain valuable insights into your system’s behavior, allowing for better optimization, diagnostics, and overall gaming experience.