The Ultimate Guide to Installing & Using Gamescope on Linux

1. What Is Gamescope?

2. Quick‑Start (in ~5 min)

This assumes you run a recent Ubuntu/Debian‑based distro with the default GNOME/KDE desktop. Adjust paths for other distros (see Section 3).

# 1️⃣ Install dependencies (Vulkan, git, build tools)
sudo apt update
sudo apt install -y git build-essential meson ninja-build pkg-config \
    libdrm-dev libgbm-dev libegl1-mesa-dev libwayland-dev \
    libx11-dev libx11-xcb-dev libxkbcommon-dev \
    libvulkan-dev vulkan-tools

# 2️⃣ Clone, build, and install Gamescope
git clone https://github.com/ValveSoftware/gamescope.git
cd gamescope
meson setup build --prefix /usr/local
ninja -C build
sudo ninja -C build install

# 3️⃣ Verify installation
gamescope --version   # should print “gamescope 1.13”

# 4️⃣ Run a game through Gamescope (example: Steam’s Proton‑GE)
#   – Replace <appid> with the Steam game’s AppID or launch any other binary.
gamescope -W 1920 -H 1080 -w 1280 -h 720 -r 60 %command%

# 5️⃣ Steam integration (simple method)
#    Open Steam → Settings → Steam Play → “Enable Steam Play for all titles”.
#    Then add a *launch option* to a game:
#      gamescope -W 1920 -H 1080 -w 1280 -h 720 -r 60 %command%

That’s it! You now have a scaled, FPS‑capped window running your game.

3. Full Installation Walk‑through

3.1. Choose Your Installation Method

Below are step‑by‑step instructions for each method.

3.2. Installing via Distro Packages

3.2.1. Ubuntu / Debian (22.04+)

sudo add-apt-repository ppa:kgraefe/gamescope
sudo apt update
sudo apt install gamescope

NOTE – The PPA provides the latest stable release. If you prefer the official Ubuntu repo, the version may be older (gamescope 1.10 as of 22.04).

3.2.2. Arch / Manjaro

sudo pacman -S gamescope
# Or, for the bleeding edge, use the AUR:
yay -S gamescope-git

3.2.3. Fedora

sudo dnf install gamescope

3.2.4. openSUSE

sudo zypper install gamescope

3.2.5. Verify

gamescope --help | head -n 5

If you see the help output, you’re ready to go.

3.3. Installing via Flatpak

flatpak install flathub org.freedesktop.Platform.VulkanLayer.gamescope
# Some distros ship gamescope directly as a runtime:
flatpak install flathub org.freedesktop.Platform.VulkanLayer.gamescope

# Run a test:
flatpak run org.freedesktop.Platform.VulkanLayer.gamescope --version

Important – When using Flatpak‑installed games (e.g., a Flatpak version of Steam), you must launch gamescope inside the same sandbox or use the --filesystem=host permission to let gamescope access the GPU.
Example:

flatpak run --filesystem=host --device=dri \
    org.freedesktop.Platform.VulkanLayer.gamescope \
    -W 1920 -H 1080 -w 1280 -h 720 -r 60 %command%

3.4. Building from Source (the “Hero” Way)

3.4.1. Prerequisites

3.4.2. Clone & Patch (if you want custom patches)

# Clone the repo
git clone https://github.com/ValveSoftware/gamescope.git
cd gamescope

# Optional: checkout a specific tag (e.g., v1.13)
git checkout v1.13

# If you have your own patches, copy them into a folder `patches/` and apply:
for p in patches/*.patch; do git apply "$p"; done

3.4.3. Configure Build

Gamescope’s build system is Meson. Most options are auto‑detected, but you can enable/disable features via -D flags.

Example: Build with HDR + FSR + NIS

meson setup build \
    --prefix /usr/local \
    -Dhdr=true \
    -Dfsr=true \
    -Dnis=true \
    -Dbuildtype=release

3.4.4. Compile

ninja -C build        # parallel compile (uses all cores)

If you see “ninja: built target gamescope” you’re good.

3.4.5. Install

sudo ninja -C build install

The binary will be placed in /usr/local/bin/gamescope.

3.4.6. Post‑install: Refresh the Vulkan loader cache

# On most distros this is automatic, but run it just in case:
sudo ldconfig

4. Understanding the Core Options

Gamescope’s command line is rich but intuitive. Below is a breakdown of the most common flags and how they combine.

Example combo:

gamescope -W 2560 -H 1440 -w 1280 -h 720 -r 60 -s nis %command%

Renders the game at 1280×720, up‑scaled with Nvidia Image Scaling (NIS), outputting 2560×1440 at a strict 60 fps.

4. Using Gamescope with Steam

4.1. The Simple “Launch‑Option” Method (Works everywhere)

1. Open Steam → Library.
2. Right‑click the game → Properties → General → Launch Options.
3. Paste a Gamescope command, e.g.:

gamescope -W 1920 -H 1080 -w 1280 -h 720 -r 60 %command%

1. Close the dialog and Launch the game.

Steam will replace %command% with the actual binary (or Proton wrapper) and pipe it through Gamescope.

4.1.1. Example for a Proton‑based game

gamescope -W 2560 -H 1440 -w 1920 -h 1080 -r 144 -e %command%

• -e enables HDR (if your driver & monitor support it).
• -r 144 caps the FPS to 144 Hz – perfect for a 144 Hz monitor.

4.2. The “Per‑Game Steam‑Deck‑Style” Shortcut (Desktop Mode)

Gamescope ships a Steam‑deck‑compatible wrapper called gamescope-session. This wrapper automatically:

• Detects the game’s preferred internal resolution (via SDL_VIDEO_X11_WMCLASS or PROTON_USE_* env vars).
• Inserts a MangoHUD overlay if present.
• Starts Gamemode if installed.

Installation (Ubuntu/Debian):

sudo apt install gamescope-session

Usage:

1. In Steam, go to Properties → Launch Options.
2. Enter:

gamescope-session %command%

That’s all – the wrapper does the rest (detects your monitor, picks a sensible scaler, and applies a 60 fps limit by default).

Tip: If you want a different internal resolution, add -w/-h after gamescope-session:

gamescope-session -w 1280 -h 720 %command%

4.3. Using Gamescope as a Standalone Launcher (outside Steam)

Sometimes you want to launch a non‑Steam game (e.g., a Lutris‑installed title) through Gamescope.

# Example: launch a native Vulkan game
gamescope -W 1920 -H 1080 -w 1920 -h 1080 -r 120 ./my_vulkan_game

If the game uses OpenGL, you must tell Gamescope to wrap the OpenGL context via -b (fallback to EGL). However, most modern games are Vulkan‑based, and Gamescope works natively with Vulkan.

5. Advanced Features & “Hero” Tricks

5.1. Dynamic Resolution Scaling (DRS)

DRS lets you keep the output resolution constant while rendering at a lower internal resolution. Great for:

• Battery‑saving on handhelds (Steam Deck, laptops).
• Reducing heat/CPU load on weak GPUs.

Syntax:

gamescope -W <outputW> -H <outputH> -w <internalW> -h <internalH> [...]

Dynamic example: (toggle internal resolution on the fly with Ctrl+Alt+F1 – see Section 6)

gamescope -W 1920 -H 1080 -w 1280 -h 720 -r 60 %command%

You can bind a script to a hotkey that cycles through a list of internal resolutions:

#!/usr/bin/env bash
# file: ~/bin/gamescope-drs-toggle.sh
RES_LIST=("1280x720" "1600x900" "1920x1080")
CURRENT=$(gamescope --list-scales | grep "Current internal" | awk '{print $4}')
INDEX=0
for i in "${!RES_LIST[@]}"; do
    if [[ "${RES_LIST[$i]}" == "$CURRENT" ]]; then
        INDEX=$(( (i+1) % ${#RES_LIST[@]} ))
        break
    fi
done
NEW=${RES_LIST[$INDEX]}
IFS='x' read -r W H <<< "$NEW"
exec gamescope -W 1920 -H 1080 -w $W -h $H -r 60 %command%

Add a global hotkey (see Section 6) that runs ~/bin/gamescope-drs-toggle.sh.

5.2. Scaling Algorithms (FSR, NIS, etc.)

Gamescope ships several scalers; you can select one with -s.

Example: Use FSR for a 1080p monitor while rendering at 720p:

gamescope -W 1920 -H 1080 -w 1280 -h 720 -s fsr -r 60 %command%

5.3. HDR Support

HDR works when:

1. Your GPU driver supports VK_EXT_hdr_metadata (most recent Mesa 23.0+, NVIDIA 560+).
2. The monitor is in HDR mode (often toggled via your desktop’s display settings).

Enable in Gamescope:

gamescope -e -W 1920 -H 1080 -w 1920 -h 1080 %command%

If you see a “HDR metadata not available” warning, verify:

vulkaninfo | grep -i hdr

You should see VK_EXT_hdr_metadata. If not, update your driver or install the latest Mesa.

5.4. FreeSync / Adaptive‑Sync

Gamescope can hand‑off the monitor’s variable‑refresh timing to the compositor. Use -t:

gamescope -t -W 1920 -H 1080 -w 1920 -h 1080 -r 60 %command%

FreeSync works automatically on AMD and recent Intel drivers; on NVIDIA you need the NVIDIA‑Vulkan driver with Variable Refresh Rate enabled.

5.5. Borderless‑Window (Hand‑Held) Mode

For handhelds (Steam Deck, laptops with external monitor) you often want a borderless window that fills the screen but still lets you switch workspaces.

gamescope -b -W 1920 -H 1080 %command%

-b tells Gamescope to ignore the compositor’s vsync and present a borderless surface that can be moved like any other window.

5.6. Combining with Other Overlays

Gamescope works hand‑in‑hand with many popular overlay tools:

Example one‑liner (Steam launch option):

gamemode -r gamescope -W 1920 -H 1080 -w 1280 -h 720 -r 60 mangohud %command%

6. Custom Key‑Bindings & Hotkeys

Gamescope can listen to key events (via libevdev) and expose them as environment variables for your scripts. This is perfect for on‑the‑fly resolution changes, FPS caps, or toggling scalers.

6.1. Enabling the Hotkey Listener

Add -k (or --keybinds) to the command line:

gamescope -k -W 1920 -H 1080 -w 1280 -h 720 -r 60 %command%

Now Gamescope will watch for key presses defined in gamescope.cfg (see next section).

6.2. Creating ~/.config/gamescope/gamescope.cfg

# ~/.config/gamescope/gamescope.cfg
# Syntax: <key> <action> [args...]

# Toggle FPS cap (60 → uncapped → 30)
F12 toggle_fps 60 30

# Cycle internal resolution (DRS)
F11 cycle_resolution 1280x720 1600x900 1920x1080

# Switch scaler
F10 cycle_scaler linear fsr nis bicubic

# Toggle HDR on/off (if supported)
F9 toggle_hdr

# Toggle FreeSync (adaptive sync)
F8 toggle_freesync

# Exit gamescope (useful for testing)
Ctrl+Shift+Q quit

Key format: Use standard X11/Wayland key names (F1‑F12, Ctrl+, Shift+, Alt+).

Supported actions (built‑in):

Reload config without restarting:

gamescope -R

(-R tells Gamescope to re‑read the config file.)

6.3. Example: Hotkey‑Driven DRS Script

Create ~/bin/gamescope-drs-toggle.sh:

#!/usr/bin/env bash
# Toggle between 1920x1080 (native) and 1280x720 internal resolution.
CURRENT=$(gamescope --list-scales | grep "Internal" | awk '{print $4}')
if [[ "$CURRENT" == "1920x1080" ]]; then
    NEW_W=1280
    NEW_H=720
else
    NEW_W=1920
    NEW_H=1080
fi
exec gamescope -W 1920 -H 1080 -w $NEW_W -h $NEW_H -r 60 %command%

Make it executable:

chmod +x ~/bin/gamescope-drs-toggle.sh

Add to gamescope.cfg:

F7 exec ~/bin/gamescope-drs-toggle.sh

Now pressing F7 while a game runs will instantly switch the internal resolution.

7. Integrating with System‑Wide Launchers (Desktop Files)

If you want a desktop shortcut that always launches a game via Gamescope, create a .desktop file.

7.1. Sample .desktop for a non‑Steam game

[Desktop Entry]
Name=My Vulkan Game (Gamescope)
Exec=gamescope -W 1920 -H 1080 -w 1280 -h 720 -r 60 /home/user/games/mygame/mygame_executable
Icon=/home/user/games/mygame/icon.png
Type=Application
Categories=Game;

Place this file in ~/.local/share/applications/. It will appear in your application menu.

8. Debugging & Performance Tuning

8.1. Enabling Verbose Logging

gamescope -D

Logs go to stdout. Pipe to a file for later analysis:

gamescope -D %command% 2>&1 | tee ~/gamescope.log

8.2. Checking Vulkan Layer Loading

If overlays aren’t showing up, verify that Gamescope loads the expected layers:

VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_DEBUG_UTILS=1 gamescope -D %command%

Look for lines containing VK_LAYER_MESA_overlay.

8.3. Measuring FPS

MangoHUD shows FPS, but Gamescope also prints a frame counter when you press Ctrl+F1 (default).

gamescope -k -W 1920 -H 1080 -r 60 %command%

Press Ctrl+F1 → you’ll see a tiny overlay with FPS, internal resolution, and scaler.

7. Running Gamescope on Multi‑Monitor Setups

When you have multiple displays, you may want Gamescope to output to a specific monitor.

7.1. List available displays

gamescope --list-displays

Typical output:

0: DP-1 (1920x1080)
1: HDMI-A-1 (2560x1440)
2: eDP-1 (1920x1080)

7.2. Force a monitor

gamescope -m HDMI-A-1 -W 2560 -H 1440 %command%

If you want Gamescope to mirror the desktop on the external monitor while the internal display stays on the game, use:

gamescope -m HDMI-A-1 -F -W 2560 -H 1440 %command%

8. Systemd Service for Gamescope (Auto‑Start on Login)

If you always want your desktop environment to run under Gamescope (similar to using Xorg), you can create a systemd user service.

8.1. Create ~/.config/systemd/user/gamescope.service

[Unit]
Description=Gamescope Session
After=graphical-session.target

[Service]
ExecStart=/usr/local/bin/gamescope -W 1920 -H 1080 -f %i
Restart=always
Environment=DISPLAY=:0
Environment=WAYLAND_DISPLAY=wayland-0

[Install]
WantedBy=default.target

8.2. Enable & Start

systemctl --user enable gamescope.service
systemctl --user start gamescope.service

Now every time you log in, your session will be wrapped by Gamescope. This is experimental – many DEs (GNOME, KDE) may not behave perfectly, but it works for i3, bspwm, and Sway.

9. Troubleshooting Common Issues

10. Performance Benchmarks (Quick Reference)

Numbers are illustrative; real‑world results depend on game engine and settings.

11. Frequently Asked Questions (FAQ)

Q: Can I use Gamescope with non‑Vulkan games (DirectX via Proton)?
A: Yes. Proton translates DirectX to Vulkan; Gamescope will see the Vulkan backend. For OpenGL games, you may need the -b flag or run via gamescope-session which includes a small OpenGL‑to‑Vulkan wrapper.

Q: Does Gamescope interfere with Steam’s built‑in FPS limiter?
A: No. Gamescope’s -r cap is independent and more accurate because it directly controls the compositor’s frame timing.

Q: Can I run two Gamescope instances simultaneously (e.g., two games on two monitors)?
A: Yes, as long as each uses a distinct -m monitor identifier and distinct output resolutions.

Q: Will Gamescope work on Wayland‑only sessions (e.g., GNOME on Wayland)?
A: Absolutely – Gamescope is a Wayland compositor itself, so it can run as a nested compositor.

Q: Is there a way to launch Gamescope automatically when starting Steam?
A: Use the Steam launch option gamescope-session %command% for each game, or set a global shortcut in your desktop environment to prepend gamescope to any launched game.

12. Summary Cheat‑Sheet

# Basic full‑screen launch
gamescope -f -W $(xrandr | grep '*' | awk '{print $1}') %command%

# DRS with FSR scaler, 60 fps cap
gamescope -W 1920 -H 1080 -w 1280 -h 720 -s fsr -r 60 %command%

# HDR + Adaptive Sync
gamescope -e -t -W 2560 -H 1440 %command%

# Borderless (hand‑held)
gamescope -b -W 1920 -H 1080 %command%

# Hotkey enabled
gamescope -k -W 1920 -H 1080 -w 1280 -h 720 -r 60 %command%

Add the appropriate launch option in Steam or run from the terminal for non‑Steam games.

13. References & Further Reading

• Gamescope GitHub Repository – https://github.com/ValveSoftware/gamescope
• Gamescope Manual – man gamescope (installed with the binary).
• Valve's Documentation on FSR/NIS – https://github.com/ValveSoftware/graphics-fidelity