Steam launch options for Gamescope on Linux, with examples

What Gamescope is and what it fixes

Gamescope is Valve's micro-compositor, the same one behind the Steam Deck's game mode. On a desktop it runs nested: it opens one window on your existing X11 or Wayland session, and the game renders into that window instead of straight onto your desktop. Everything the game does happens inside a display Gamescope owns.

That indirection is the point. Because Gamescope controls the surface, it can:

• present a fixed output resolution while the game renders at a different one, and upscale between the two with FSR, NIS, or integer scaling;
• cap the refresh rate the game sees, which caps its frame rate without a separate limiter;
• expose HDR to the game on a session that supports it;
• turn windowed or borderless games into a real fullscreen window;
• keep a game that fights your compositor (wrong resolution on exit, stolen focus, a cursor that wanders onto a second monitor) contained in its own window.

None of that needs per-game patches. You describe the window you want with flags, and Gamescope makes the game live inside it. This guide covers the flags that turn up most; every flag, with defaults and accepted values, is in the Gamescope flags reference.

The launch-option pattern

Steam substitutes %command% with the real game command line. Anything in front of it wraps the game. The shape is always:

gamescope <flags> -- %command%

Set it under Properties, General, Launch Options for the game. Two things people forget:

1. The -- separator. Gamescope's option parser stops at --; without it, Gamescope tries to read the game's own arguments as its flags and fails.
2. %command% itself. Leave it off and Steam runs gamescope <flags> -- with nothing to launch. Gamescope opens an empty window or exits at once.

Environment variables go in front of gamescope, not after --: DXVK_HDR=1 gamescope --hdr-enabled -f -- %command%. Everything after -- belongs to the game.

The flags people actually use

Gamescope has dozens of options (gamescope --help lists them all). These are the ones that turn up in real launch options.

The uppercase and lowercase pairs trip people constantly: uppercase is what the display gets, lowercase is what the game draws. Swap them and you get a small image centered on a large black surface.

Five copy-paste examples

1440p monitor, game rendered at 1080p with FSR. About 44 percent fewer pixels to shade, upscaled with sharpening.

gamescope -W 2560 -H 1440 -w 1920 -h 1080 -F fsr --fsr-sharpness 5 -f -- %command%

4K TV with HDR. Needs a Wayland session with HDR switched on in the desktop's display settings (KDE Plasma 6 or another compositor with HDR support), plus DXVK's HDR path for Proton games.

DXVK_HDR=1 ENABLE_HDR_WSI=1 gamescope -W 3840 -H 2160 -r 120 --hdr-enabled --adaptive-sync -f -- %command%

Capping a menu-heavy game to 60. Games that render menus at a thousand frames per second spin fans and whine coils; a 60 Hz nested display fixes it without touching in-game settings, and -o 30 drops it further when alt-tabbed.

gamescope -W 2560 -H 1440 -r 60 -o 30 -f -- %command%

Handheld or Steam Deck-style target. A 1280x800 panel, 40 fps for battery, cursor kept inside, borderless so the window does not fight the shell.

gamescope -W 1280 -H 800 -w 1280 -h 800 -r 40 -b --force-grab-cursor -- %command%

Wayland cursor problems. A game that keeps dropping the pointer onto your other monitor, or a Wayland-native game that misbehaves under XWayland.

gamescope -W 2560 -H 1440 -f --force-grab-cursor --expose-wayland -- %command%

Combining Gamescope with MangoHud

There are two ways, and they are not equivalent.

mangohud %command% inside Gamescope injects the overlay into the game process. It works, but the HUD is drawn at the game's render resolution and then upscaled with it, so under FSR the numbers look soft.

gamescope -W 2560 -H 1440 -w 1920 -h 1080 -F fsr -f -- mangohud %command%

--mangoapp runs MangoHud as a separate client inside the Gamescope session. Gamescope's own help text recommends it over wrapping the game. The overlay is drawn at output resolution and survives the game recreating its swapchain. The trade-off: mangoapp reads ~/.config/MangoHud/MangoHud.conf (or MANGOHUD_CONFIGFILE) but not per-game wine-<exe>.conf files, because it is not inside the game process.

gamescope -W 2560 -H 1440 -f --mangoapp -- %command%

Either way, MangoHud config explained covers what goes in the file.

Heroic and Lutris: same command, different field

Heroic and Lutris have no %command%. They append the game command for you, so you supply the prefix ending in --.

Heroic:

1. Open the game's settings (the gear icon on the game page).
2. Under Advanced, find Wrapper command. Enter gamescope as the wrapper and the flags plus -- as its arguments, for example -W 2560 -H 1440 -f --.
3. Recent Heroic builds also have a dedicated Gamescope section with resolution, upscaler, and FPS-limit fields that generate the same thing. Use one or the other, not both.

Lutris:

1. Right-click the game and choose Configure.
2. On the System options tab, find Command prefix. Enter gamescope -W 2560 -H 1440 -f --.
3. Lutris also has a Gamescope toggle under System options that exposes output and game resolution and an FPS limit; it writes an equivalent prefix.

Both launchers pass the result through a shell, so the same flags and the same -- rule apply.

Where ProtonShift fits

If you are configuring more than one or two games, hand-editing these strings gets old. ProtonShift's Gamescope builder is a form over exactly this command: output and game resolution fields with common presets, an FPS limit, an FSR switch with a sharpness slider, HDR, fullscreen and borderless toggles, and a free-text field for any other flag. The preview updates as you edit. One button adds it to the launch options of the game selected in the Library (replacing an existing gamescope line instead of nesting a second one), and another copies it to the clipboard for pasting into Steam, Heroic, or Lutris.

Specific things the builder does that matter for correctness:

• It writes -W/-H for output and -w/-h for game resolution, so the uppercase and lowercase mix-up cannot happen.
• Turning on FSR emits -F fsr together with --fsr-sharpness, with the value clamped to 0 through 20. An earlier version emitted only the sharpness flag, which silently did nothing; that was fixed.
• Extra arguments are parsed with shell quoting rules, so quoted values survive, and the command always ends in -- %command% (since 1.3.0; earlier versions left %command% off).
• It checks whether gamescope is installed on the host, including from inside the ProtonShift Flatpak, and says so if it is missing while still letting you build a command.
• It can emit a ScopeBuddy wrap (SCB_AUTO_RES=1 SCB_AUTO_HDR=1 scb --) instead of a raw command, for setups where ScopeBuddy reads the monitor's mode, HDR, and VRR state at launch. A separate ScopeBuddy editor manages scb.conf and per-app overrides.

What it does not do: validate flag names in the free-text field. Unknown flags pass through to Gamescope, which rejects them at launch, so check gamescope --help for anything unusual. The Getting Started docs cover installation.

Troubleshooting

Black screen, game audio plays. Most often the resolution flags are inverted (-w/-h larger than -W/-H). Second most often: --hdr-enabled on a session without HDR. Remove flags until it works, then add them back one at a time. Running the full command from a terminal shows Gamescope's log.

Wrong monitor. In nested mode Gamescope opens wherever your desktop places new windows. -O/--prefer-output only applies to Gamescope's embedded DRM session, not to a nested window. Start with -b instead of -f, move the window, then go fullscreen, or make the intended monitor primary in your desktop's display settings.

Mouse stuck or escaping. --force-grab-cursor fixes the escaping case. If the cursor is stuck or invisible instead, remove --force-grab-cursor; the game probably expects an absolute pointer. -g grabs the keyboard, which is a different thing.

gamescope: command not found with Flatpak Steam. Flatpak Steam cannot see binaries on your host. Install the Flathub Gamescope extension for Steam's runtime:

flatpak install flathub org.freedesktop.Platform.VulkanLayer.gamescope

If Flatpak asks for a branch, pick the one matching the runtime shown by flatpak info com.valvesoftware.Steam. Native Steam just needs the distro package, named gamescope on Arch, Fedora, and Ubuntu.

Game launches outside the Gamescope window. Publisher launchers that spawn the real game as a second process can escape. --force-windows-fullscreen helps for games that open a small window inside the session; for launcher chains, add the game's own skip-launcher argument after %command%.