Home
Docs

Documentation

Getting Started

Install, launch, and let ProtonShift find your games. No terminal gymnastics. No JSON spelunking. No winetricks arcana.

Step 1 → 2

Quick start

From download to a tuned game in under three minutes.

1Install ProtonShift

There's no packaged release yet — the Flatpak local build is the supported path, and a Flathub submission is in prep. Two commands after a clone, and nothing leaks into your system packages. Tagged releases on GitHub Releases also attach a prebuilt .flatpak bundle:

1 · One-time tooling

$ flatpak install -y flathub org.flatpak.Builder org.freedesktop.Sdk//24.08

2 · Get the source

$ git clone https://github.com/I4cTime/protonshift && cd protonshift

3 · Build + install

$ flatpak run org.flatpak.Builder --user --install --force-clean build-dir flatpak/io.github.i4ctime.protonshift.yml

4 · Run

$ flatpak run io.github.i4ctime.protonshift

The only outside dependencies are the game tools you actually want to manage — Steam, Heroic, Lutris, MangoHud, Gamescope, ScopeBuddy, Protontricks, GameMode.

2First steps

Launch the app and your library builds itself — Steam, Heroic (Epic + GOG), and Lutris games are discovered automatically, native and Flatpak installs alike. From there:

Type in the library search to jump straight to a game — per-source counts show what came from where.
Open the launch options editor and flip a quick preset — GameMode, NVIDIA dGPU, MangoHud, Proton Log, or ScopeBuddy. Presets grey out with an install hint if their tool isn't installed.
Pick a Proton or Wine version from the dropdown instead of hunting through config files.
Build a Gamescope command with sliders, choose a MangoHud preset, and save the whole setup as a profile.

Guides

Feature guides

Every major surface of the app, and what it does for you.

Library

Steam, Heroic (Epic + GOG), and Lutris discovered automatically — native and Flatpak. Search everything at once; launch, copy App IDs, open prefixes.

Launch options

A real editor for per-game launch options, with quick presets for GameMode, NVIDIA dGPU offload, MangoHud, Proton logging, and a ScopeBuddy wrapper.

Gamescope

Build the full gamescope command with resolution pickers, FPS limit, FSR sharpness, HDR, and a live preview — or emit a ScopeBuddy override instead.

ScopeBuddy

Edit the global scb.conf and per-app overrides under scb.conf.d/ with a KV editor, plus reusable env snippets. Comments are preserved on write.

MangoHud

Visual editor for global and per-game configs — metrics by category, overlay position, hotkey — plus eight presets from Minimal to Streaming.

Environment variables

Persistent gaming env vars via ~/.config/environment.d/ with explained presets: NVIDIA/AMD tuning, DXVK, shader cache, Wayland, debug flags.

Profiles

Save a complete setup — launch options, compat tool, env vars, power profile — as a named profile and restore or transplant it later.

Prefixes

Inspect Wine prefixes without a terminal: size, detected DXVK/VKD3D versions, open in file manager, delete with confirmation.

Saves

Auto-detected save locations, timestamped ZIP backups under ~/.config/protonshift/backups/, and one-click restore.

Fixes

A database of known fixes matched per App ID plus universal fixes — env vars, launch args, or both, applied in one click.

System

GPU detection with live temps (nvidia-smi / DRM sysfs), power profile switching via system76-power or power-profiles-daemon, and session info.

Displays

Per-monitor outputs, modes, and resolution/refresh-rate switching over xrandr, wlr-randr, or kscreen-doctor, depending on your session.

Controllers

Auto-detect pads, generate SDL mapping strings, and prove everything in the live gamepad tester — buttons, axes, triggers, rumble.

Themes

Six built-in palettes plus a System option that follows your OS light/dark preference — switchable in-app, tokens via a Theme.qml singleton.

Transparency

Where your configs live

ProtonShift edits real files in real places — atomically — so you can always inspect, back up, or hand-edit them.

MangoHud

fps_limit=144
cpu_temp
gpu_temp
frame_timing
position=top-left
toggle_hud=Shift_R+F12

ScopeBuddy

SCB_GAMESCOPE_ARGS="-W 2560 -H 1440 -r 144 -f"
SCB_AUTO_RES=1
SCB_AUTO_HDR=1
SCB_AUTO_VRR=1

Environment variables

# Applied at login, survives reboots
DXVK_ASYNC=1
PROTON_ENABLE_NVAPI=1
__GL_SHADER_DISK_CACHE_SKIP_CLEANUP=1

ProtonShift itself

backups/   # timestamped save-game ZIPs
fixes/     # your user-contributed game fixes
profiles/  # saved configuration profiles

Reference

Pages reference

Every page of the app with its capabilities. 12 pages, one tab away.

Capabilities

source badgesper-source countscross-source searchone-click launchcopy App IDopen install folderopen Wine prefix

Quick access

Library → type a game name in search

Capabilities

launch options editorquick presets (GameMode, NVIDIA dGPU, MangoHud, Proton Log)Proton / Wine tool dropdownHeroic toggles (Esync, Fsync, DXVK/VKD3D)ScopeBuddy override cardMangoHud deep linkProtontricks verbs

Quick access

Library → select a game

launch options: gamemoderun mangohud %command%

Capabilities

720p/1080p/1440p/4K quick buttonsFPS limiterFSR + sharpness sliderHDR / fullscreen / borderlesslive command previewinsert into launch optionsdistro install hints

Quick access

gamescope -W 2560 -H 1440 -r 144 -F fsr -f -- %command%

Capabilities

global scb.conf KV editorSCB_GAMESCOPE_ARGS / SCB_AUTO_RES / SCB_AUTO_HDR / SCB_AUTO_VRR …per-app overrides (create, edit, duplicate, delete)install hints (Bazzite, Fedora Terra, AUR, NixOS)

Quick access

~/.config/scopebuddy/scb.conf.d/620.conf

Capabilities

metrics by category (Performance, CPU, GPU, Memory, I/O, System)overlay position + font + alphatoggle hotkeylog folder8 presets: Minimal → Debug

Quick access

~/.config/MangoHud/MangoHud.conf

Capabilities

Proton NVIDIA / AMD presetsDXVK / VKD3D tuningshader cache settingsWayland compatibilityProton debug flags

Quick access

~/.config/environment.d/70-protonshift.conf

Capabilities

captures launch options + compat tool + env vars + power profileauto-highlight on matching game / App IDoptional system-wide restore

Quick access

Game Detail → Profiles → Save as profile

Capabilities

prefix sizeDXVK version (from d3d11.dll)VKD3D-Proton version (from d3d12.dll)open in file managerdelete with confirmation

Quick access

~/.steam/steam/steamapps/compatdata/<appid>/pfx

Capabilities

Proton prefix + Steam userdata detectionper-directory sizesBackup Allbrowse + restore previous backups

Quick access

~/.config/protonshift/backups/

Capabilities

env vars and/or launch argumentsone-click apply into launch optionsuser-contributed fixes

Quick access

~/.config/protonshift/fixes/

Capabilities

NVIDIA via nvidia-smi, AMD/Intel via DRM sysfslive temps + VRAMperformance / balanced / battery saversystem76-power + powerprofilesctlxrandr (X11) / wlr-randr (Wayland)

Quick access

System → Power profile → Performance

Capabilities

Xbox / PlayStation / Nintendo / generic detectionSDL_GAMECONTROLLERCONFIG mapping stringslive button / axis / trigger metersrumble test

Quick access

Controllers → Test gamepad

When things break

Troubleshooting

Known issues and their fixes — most are already shipped, so updating usually solves it.

There's no download on the releases page

There's no packaged release yet — the Flatpak local build (two commands, see Install above) is the supported path, and a Flathub submission is in prep under flatpak/flathub/. Tagged GitHub releases attach a prebuilt .flatpak bundle built by CI.

GPU stats, power profiles, or display switching don't work inside the Flatpak

Host tools like nvidia-smi, powerprofilesctl, and xrandr live outside the sandbox — ProtonShift detects the sandbox via /.flatpak-info and routes every host command through flatpak-spawn --host, so the same code path works native or sandboxed. If something still comes up empty, rebuild from the current main and open an issue with the terminal output.

A launch preset (GameMode, MangoHud, ScopeBuddy…) is greyed out

That's tool detection working: the preset's underlying tool wasn't found on your system, and the grey state carries an install hint. Install the tool (on Bazzite and SteamOS most are pre-installed) and the preset lights up.

A page appears stuck in a loading state

Fixed in v1.0.0 — exceptions on background worker threads are now routed to an error signal instead of silently killing the thread, so the UI surfaces the error and recovers. Update, and if it recurs, run flatpak run io.github.i4ctime.protonshift from a terminal and open an issue with the output.

Still stuck? Open an issue — run flatpak run io.github.i4ctime.protonshift from a terminal and include the output.

AGPL-3.0

Contributing

PRs are welcome. The full contributor guide — project layout, the PySide6/QML threading pattern, and the release process — lives in ARCHITECTURE.md.

run from source

# One command: venv + editable install + launch
$ ./run.sh

# Or manually
$ python3 -m venv .venv && . .venv/bin/activate
$ pip install -e ".[dev]"
$ python -m protonshift

# Checks (same as CI)
$ ruff check protonshift && pytest

The pytest suite is Qt-free by design, and CI runs ruff, pyside6-qmllint, and the tests on Python 3.11 and 3.12. Start with ARCHITECTURE.md.

Ready to shift into gear?

Explore features View changelog