MangoHud config explained: the settings that matter

Where the config lives and which file wins

MangoHud reads plain text files with one option per line. It looks in this order and uses the first file it finds:

The executable is the process MangoHud actually loads into, not the launcher you clicked. For a game whose Windows binary is Overwatch.exe, the file is wine-Overwatch.conf even if you launched Battle.net.exe. ps -e while the game is running shows the real name.

Environment variables override files. MANGOHUD_CONFIG=fps,cpu_temp,position=top-right applies only those options and ignores every file unless the first item is read_cfg. MANGOHUD_CONFIGFILE=/path/to/file points at a specific file, which is the fix for engines whose executable name is unhelpful (java, python). Flatpak Steam has its own home under ~/.var/app/com.valvesoftware.Steam/, so its MangoHud reads ~/.var/app/com.valvesoftware.Steam/config/MangoHud/MangoHud.conf, not the one in your real ~/.config.

A minimal config, line by line

Options without a value are switches; options with = take a value. # starts a comment.

# ~/.config/MangoHud/MangoHud.conf
fps
frametime
cpu_temp
gpu_temp
ram
vram
position=top-left
font_size=24
background_alpha=0.4

• fps: current frames per second. Nearly everything else is optional.
• frametime: time per frame in milliseconds. A steady 16.7 ms matters more than a high average; stutter shows up here first.
• cpu_temp, gpu_temp: package temperatures from the kernel's hwmon sensors. If one is blank, see troubleshooting.
• ram, vram: system memory and video memory in use. vram climbing toward the card's limit explains sudden stutter during texture streaming.
• position: one of eight anchors: top-left, top-right, middle-left, middle-right, bottom-left, bottom-right, top-center, bottom-center.
• font_size: in pixels, default 24. See the 4K note at the end.
• background_alpha: 0 (transparent) to 1 (solid) for the panel behind the text. Default 0.5.

Add cpu_stats and gpu_stats for load percentages, frame_timing for the graph, and wine, vulkan_driver, and engine_version when filing bug reports. full enables almost every toggle at once, which is worth doing once to see what exists.

Frame limits and the keys that control them

MangoHud can cap frame rate itself, without Gamescope or in-game vsync:

fps_limit=60,120,0
fps_limit_method=late
toggle_fps_limit=Shift_L+F1

fps_limit takes one value or a comma-separated list; 0 means uncapped. With a list, toggle_fps_limit (default Shift_L+F1) cycles through the values in order, so the example above flips between 60, 120, and uncapped without leaving the game.

fps_limit_method chooses when the limiter sleeps. late waits after the frame is presented, which gives the lowest input latency and is the sensible default. early waits before presenting, which produces more even frame pacing at the cost of a little latency; try it if frametime looks jagged under a cap.

The other default hotkeys, all changeable in the file:

• toggle_hud=Shift_R+F12 shows or hides the overlay.
• toggle_hud_position=Shift_R+F11 steps through the anchors.
• toggle_preset=Shift_R+F10 cycles presets (next section).
• toggle_logging=Shift_L+F2, reload_cfg=Shift_L+F4, reset_fps_metrics=Shift_R+F9.

Key names are X11 keysyms, so Shift_R+F12 means the right Shift key. no_display starts hidden, which pairs well with a toggle key when you only want the HUD on demand.

Logging to CSV and reading it

For benchmarking, MangoHud writes CSV files. It needs an output folder; without one nothing is logged.

output_folder=/home/you/mangohud-logs
log_duration=60
autostart_log=5
log_interval=100

1. Set output_folder to an existing directory, as a full path. This alone enables logging on the hotkey.
2. log_duration=60 stops each capture after 60 seconds so runs are comparable. Omit it to log until you press the key again.
3. autostart_log=5 starts a capture five seconds after launch, for hands-off runs.
4. log_interval=100 samples every 100 ms. The default of 0 records every frame, which is more precise and produces much larger files.
5. Press Shift_L+F2, or wait for autostart. The file name is the executable plus date and time.

Each CSV opens with a header block (OS, CPU, GPU, RAM, kernel, driver) followed by per-sample columns: fps, frametime, cpu_load, gpu_load, cpu_temp, gpu_temp, clocks, VRAM and RAM in use, and elapsed time. For a quick read, sort by frametime and look at the worst 1 percent; the average fps hides exactly the stutter you are trying to find. Two runs with the same log_duration and autostart_log are directly comparable.

Presets and compact layouts

preset= selects one of MangoHud's built-in layouts and overrides the individual toggles:

preset=2,3,1 gives toggle_preset a specific cycle order. The default is -1,0,1,2,3,4, where -1 means "whatever my config file says." You can define your own numbered presets in ~/.config/MangoHud/presets.conf; MANGOHUD_PRESETSFILE points at an alternative, which matters inside Flatpak sandboxes.

For a Steam Deck-style strip instead of a panel, the pieces are horizontal (one row), hud_compact (shorter labels), hud_no_margin, and a smaller font_size. preset=2 is the quickest way there; the individual options let you tune it.

Enabling MangoHud per game or everywhere

Per game, in Steam's launch options:

mangohud %command%

MANGOHUD=1 %command% also works and only sets an environment variable. The difference: MANGOHUD=1 activates the Vulkan implicit layer, which covers every Proton game (DXVK and VKD3D-Proton translate to Vulkan) and every native Vulkan title. The mangohud wrapper additionally preloads the OpenGL hook, so native OpenGL games need it. Heroic has a MangoHud switch in per-game settings and Lutris has one under System options; both do the same thing.

Globally, export MANGOHUD=1 in your session (a ~/.config/environment.d/*.conf file on systemd desktops, or your shell profile) and every Vulkan program gets the overlay, including browsers with Vulkan enabled. Most people prefer per game.

Flatpak Steam is separate. Install the layer extension for Steam's runtime, then enable it:

flatpak install flathub org.freedesktop.Platform.VulkanLayer.MangoHud
flatpak override --user --env=MANGOHUD=1 com.valvesoftware.Steam

flatpak info com.valvesoftware.Steam shows the runtime branch (24.08, 25.08) if the install asks you to pick one. The config lives under ~/.var/app/com.valvesoftware.Steam/config/MangoHud/, and output_folder must point somewhere the sandbox can write.

Where ProtonShift fits

ProtonShift's MangoHud editor is a form over these files. It reads ~/.config/MangoHud/MangoHud.conf, shows every toggle grouped by category, and gives fields for fps_limit, position, font_size, background_alpha, toggle_hud, and output_folder. Eight starting presets (minimal, standard, full, fps-only, cpu-gpu, benchmark, battery-saver, streaming) fill in a sensible set: battery-saver sets fps_limit=30 with a faint background, and benchmark turns on the logging metrics with an output_folder.

How it writes matters more than what it shows. Saving merges into your existing file: comments and blank lines stay where they were, changed options are updated in place, options you switched off are removed, and new ones are appended. The write is atomic, and if the file could not be read the editor refuses to save over it. A hand-edited config with notes survives a round trip.

Per-game overrides get the same editor from a game's detail page. ProtonShift writes them as ~/.config/MangoHud/wine-<Name>.conf, using the library name with spaces replaced by underscores. MangoHud matches on the executable name, so if a game's binary is not called what the store lists, rename the file to match; the rules in the first section apply.

The launch-options editor has a one-click MANGOHUD=1 preset that greys out with an install hint when mangohud is not on the system. The editor writes to your real ~/.config, which is what native Steam, Heroic, and Lutris read; for Flatpak Steam, copy the finished file into the sandbox path above. Getting Started covers installation.

Troubleshooting

No HUD in a Proton game. Confirm the game is actually using Vulkan: DXVK and VKD3D-Proton are, but a game forced to PROTON_USE_WINED3D=1 is OpenGL and needs mangohud %command%. Check that the launch option is on the game you launched, and that a second copy is not loading through a Heroic toggle plus a launch option at the same time.

No HUD in a native OpenGL game. Use mangohud %command% rather than MANGOHUD=1. If the game crashes at start or still shows nothing, try MANGOHUD_DLSYM=0 mangohud %command%; a few engines conflict with the dlsym hook. Games that set their own LD_PRELOAD can drop MangoHud's, and there is no clean fix short of editing the game's launch script.

HUD in the wrong corner, or it moves. A per-game file or MANGOHUD_CONFIG is overriding position. Remember the precedence: game directory, then per-executable, then global, with the environment variable above all of them. toggle_hud_position may also have been pressed; it does not persist.

Huge font on a 4K display. MangoHud does not scale for DPI. font_size=24 is sized for 1080p; try 36 to 48 at 2160p, or font_scale=1.5 to scale everything together. Inside Gamescope with FSR, the overlay is rendered at the game's internal resolution and upscaled with it; use Gamescope's --mangoapp to draw it at output size instead. See Steam launch options for Gamescope.

Temperature is blank. cpu_temp needs a hwmon sensor the kernel exposes (k10temp, coretemp). If sensors from lm-sensors shows nothing for the CPU, MangoHud cannot read it either; that is a kernel driver gap, usually on very new CPUs.