Gamescope flags: a complete reference

The command shape

Options come first, then a bare --, then the program to run inside the session:

gamescope [options] -- <command>

In Steam's launch options the command is %command%, so the line is gamescope [options] -- %command%. Heroic and Lutris append the game for you, so the prefix ends at --. Both the short and the long spelling of each option are listed below.

Verified against: Gamescope master at commit 6b4481c (September 20, 2026), where src/main.cpp was last changed by commit ce66094 (September 16, 2026). The newest release tag at that point was 3.16.29. Every flag below is in the gamescope_options[] table in that file; descriptions follow its help text and the README. The list was also compared with gamescope --help from a 3.16.28 install.

Check the flags your install has

Distribution packages trail master, so your build may lack the newest options. Ask the binary:

gamescope --help
gamescope --version

-h is not help. It is the short form of --nested-height and expects a number. One difference found while checking this page: the sgsr filter is in master and in the README, but a 3.16.28 build lists only linear, nearest, fsr, nis, pixel. An unknown flag or value makes Gamescope exit with See --help for a list of options, which in Steam looks like a game that never starts.

Output and game resolution

Uppercase is what your display gets. Lowercase is what the game draws.

Refresh rate, frame limiting, and VRR

Window modes

These are listed under "Nested mode options" in the help text. They affect the window Gamescope opens on your desktop and mean nothing in an embedded session.

Scaling and filters

The scaler decides the geometry: how the game's image is fitted to the output. The filter decides how pixels are sampled when the sizes differ. They are independent, so -S integer -F nearest is a valid pair.

Runtime shortcuts from the help text: Super + U toggles FSR, Super + Y toggles NIS, Super + N toggles nearest-neighbour filtering, Super + I and Super + O change sharpness.

HDR and color

Cursor and input

Wayland, Xwayland, and backends

With auto, the source picks wayland when a Wayland display is present, sdl when only DISPLAY is set, and drm otherwise.

Steam and MangoHud integration

Flags that only work in embedded (DRM) sessions

An embedded session is Gamescope driving the display itself through DRM, as on the Steam Deck. The help text lists these under "Embedded mode options". They do not apply to a nested window on your desktop, which is why -O does not fix "wrong monitor" in a Steam launch option; --display-index is the nested counterpart.

--disable-layers and --debug-layers (libliftoff hardware planes) sit with the embedded options in the source, --mura-map is listed under "Steam Deck options", and --force-orientation (left, right, normal, upsidedown) rotates the internal display. The reverse also holds: -W and -H are ignored in embedded mode, and -o, -b, -f, -g, --force-grab-cursor, and --display-index are nested-only.

Debugging and diagnostics

The option table also holds -x/--disable-xres, -R/--ready-fd, --virtual-connector-strategy, --allow-deferred-backend, --fade-out-duration, --xwayland-force-touch-pointer-emulation, --force-composition-rotation, and a --vr-* family for OpenVR builds. They are session plumbing; gamescope --help describes those that have help text.

Deprecated, renamed, and mistaken flags

• --hdr-itm-enable was the name in the option table through the 3.15 releases; 3.16 renamed it to --hdr-itm-enabled. Current builds still accept the old spelling, because the parser takes unambiguous prefixes of long options, but the new spelling fails on 3.15 and older.
• --integer-scale (-i), --nearest-neighbor-filter (-n), --fsr-upscaling (-U), and --nis-upscaling (-Y) were real flags in the 3.11 series. Release 3.12.0 replaced them with -S and -F, and current builds reject them with unrecognized option. Write -S integer, -F nearest, -F fsr, and -F nis.
• --fsr-sharpness is not deprecated. It and --sharpness set the same value, which applies to NIS as well as FSR.

Five short recipes

The long-form versions, with the HDR environment variables and the Heroic and Lutris fields, are in Steam launch options for Gamescope.

# 1080p render, FSR upscale to a 1440p fullscreen window
gamescope -W 2560 -H 1440 -w 1920 -h 1080 -F fsr --sharpness 5 -f -- %command%

# Cap at 60, drop to 30 when unfocused
gamescope -W 2560 -H 1440 -r 60 -o 30 -f -- %command%

# Pixel art: 720p game, integer scaled to 1440p
gamescope -h 720 -H 1440 -S integer -F nearest -- %command%

# HDR output with VRR
gamescope -W 3840 -H 2160 --hdr-enabled --adaptive-sync -f -- %command%

# Overlay at output resolution, cursor kept inside the window
gamescope -W 2560 -H 1440 -f --mangoapp --force-grab-cursor -- %command%

Where ProtonShift's Gamescope builder fits

ProtonShift's builder is a form over a subset of this page. Per its source, it emits -W/-H for output size, -w/-h for game size, -r for the FPS limit, -F fsr with --fsr-sharpness clamped to 0 through 20, --hdr-enabled, -f, and -b, then always appends --. A free-text field takes any other flag; it is split with shell quoting rules and passed through without validation. The builder can also emit a ScopeBuddy prefix (SCB_AUTO_RES=1 scb --) instead of a raw command.

One known defect: the builder's integer-scaling switch currently writes --integer-scale, which Gamescope rejects. Until that is fixed, leave the switch off and type -S integer into the extra-arguments field. Getting Started covers installation.