gamescope

Run a program with gamescope on the terminal

$ gamescope -- [program]

$ gamescope -- %command%

$ gamescope [[-h|--nested-height]] 720 [[-H|--output-height]] 1440 [[-S|--scaler]] integer -- [command]

$ gamescope [[-r|--nested-refresh]] 30 -- [command]

$ gamescope [[-e|--steam]] -- /usr/bin/steam -tenfoot

$ gamescope [[-O|--prefer-output]] [HDMI-A-1,DP-3,...] -- [program]

$ <Super f>

$ gamescope --help

gamescope [options] [--] [command [args...]]

-h, --help
    Show help message and exit

-v, --version
    Print version information

-C, --config <FILE>
    Load configuration from FILE

-w <WIDTH>, --width <WIDTH>
    Set application render width

-h <HEIGHT>, --height <HEIGHT>
    Set application render height

-W <WIDTH>, --output-width <WIDTH>
    Set output/display width

-H <HEIGHT>, --output-height <HEIGHT>
    Set output/display height

-e, --expose
    Run as regular (toplevel) Wayland window

-N, --nested
    Use nested Wayland backend

-f, --force-windows
    Force game into windowed mode

-F, --fullscreen
    Force game into fullscreen

-S, --force-fullscreen
    Force exclusive fullscreen

-r <RATE>, --max-framerate <RATE>
    Limit game framerate to RATE

--fps-limit <FPS>
    Limit compositor FPS

-i, --input-focus
    Force input focus to game window

--adaptive-sync
    Enable VRR/adaptive sync

--hdr-enabled
    Enable HDR output

--backend <BACKEND>
    Select backend (auto, drm, wayland, headless)

--drm-device <DEVICE>
    Use specific DRM device

-D, --desktop-resolution
    Match host desktop resolution

--dim-idle
    Dim inactive outputs

--show-cursor
    Always show cursor

--hide-cursor
    Hide cursor in game

--debug-fps
    Overlay FPS counter

--force-grab-cursor
    Grab and hide cursor

Gamescope is a Wayland compositor designed specifically for running games and applications in a controlled environment. Developed by Valve for the Steam Deck, it creates a nested compositor session that decouples the game's rendering resolution from the display output. This enables features like precise scaling (integer, fractional, super-resolution), HDR tone mapping, variable refresh rate (VRR), FPS limiting, and advanced input handling including mouse warping and controller passthrough.

It runs games (via XWayland or native Wayland) fullscreen or windowed, applying post-processing effects while minimizing latency. On desktops, it's used to enhance Wayland gaming by providing Steam Deck-like visuals and performance tweaks. Gamescope supports multiple backends (DRM/KMS primary, nested Wayland, headless), multi-monitor setups, and configuration files. Ideal for Proton/Steam games lacking native scaling, it improves sharpness on high-DPI displays without DSR/FSR hacks.

Key benefits include automatic cursor hiding, idle dimming, and debug overlays for FPS/Timings. It's lightweight, wlroots-based, and integrates with Steam's launch options via %command%.

Requires Wayland session; X11 needs XWayland. Nested mode adds latency (~1-2ms). HDR/VRR needs compatible GPU/displays (AMD/Intel best). High scaling ratios increase CPU/GPU load. Not for general desktop compositing.

Desktop scaling: gamescope -w 1280 -h 720 -W 3840 -H 2160 -- glxgears
Steam: Add to launch options: gamescope -W 1920 -H 1080 -r 60 -- %command%

Supports linear, nearest, fsr, nis, integer. Use --scaler <filter> --scale-filter-method <method> for FSR/NIS upscaling.

--debug-fps, --debug-timing, --debug-overlay for performance metrics.

Developed by Valve starting 2021 for Steam Deck (SteamOS 3.0). Open-sourced 2022 under ValveSoftware/gamescope GitHub repo. Built on wlroots library. Major updates for HDR (2023), nested improvements, and Steam Deck OLED support. Actively maintained for Proton gaming.

weston(1), sway(1), mutter(1), wlroots(7)