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

Install from the signed I4C Flatpak repository: add it once and every release after arrives with a plain flatpak update. Nothing leaks into your system packages. Tagged releases on GitHub Releases also attach a prebuilt .flatpak bundle for a one-shot install, and the repo README covers building from the manifest:

1 · Add the I4C repo (once)

$ flatpak remote-add --user --if-not-exists i4c https://flatpak.i4c.studio/index.flatpakrepo

2 · Install

$ flatpak install i4c io.github.i4ctime.protonshift

3 · Run

$ flatpak run io.github.i4ctime.protonshift

Update later

$ flatpak update

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 games and Non-Steam shortcuts, Heroic (Epic, GOG, Amazon, sideloaded), 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.
Game won't start? Per-game tools has a Launch check that lists the usual causes, and a Proton log viewer that turns on PROTON_LOG=1 and reads the log for you.
Build a Gamescope command with sliders and add it to the selected game, 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 (with Non-Steam shortcuts), Heroic (Epic, GOG, Amazon, sideloaded), and Lutris discovered automatically - native and Flatpak. Native Linux games are marked; Steam's own tools stay out of the list. 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 - placed around %command% so they never become stray game arguments.

Launch check

Per-game tools, Launch check: the usual reasons a game won't start - missing or doubled %command%, missing wrapper tools, a removed Proton build, a missing anti-cheat runtime or install folder - each with what to do. Never starts the game.

Proton log viewer

Per-game tools, Proton log: turn on PROTON_LOG=1, then read the end of steam-<appid>.log in the app, filtered to the lines that look like problems, with copy and open-file.

Gamescope

Build the full gamescope command with resolution pickers, FPS limit, FSR sharpness, HDR, and a live preview - add it to the selected game's launch options, 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.

Proton builds

Installed compatibility tools with size, version and the games that pin them, plus the latest GE-Proton releases - install with checksum verification, remove safely.

ProtonDB

Community tier, report count, confidence and trending tier for the selected Steam game, cached for a day. Sends only the App ID; opt out under Settings, Privacy.

Environment variables

Persistent gaming env vars with explained presets, written to environment.d, ~/.profile or ~/.xsessionrc - whichever your session reads - or copied as Steam launch options.

Profiles

Save a complete setup - launch options, compat tool, env vars, power profile - as a named profile; restore it, transplant it, or export/import it as a JSON bundle.

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 current temperature (nvidia-smi / DRM sysfs, read on open or Refresh), 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, hyprctl, wlr-randr, or kscreen-doctor, depending on your session. A change reverts after 15 seconds unless you keep it.

Controllers

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

Settings

In the header: Appearance (mode, four visual styles, accent override with a color picker), Sounds (three sets, volume, chimes), the ProtonDB privacy toggle, and About with a manual update check.

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 - 10 destinations, one click away. Maintenance and Per-game tools are not pages: they live inside a game's detail pane in Library.

Capabilities

source badgesnative Linux games markedSteam tools kept out of the listLutris runner + storeper-source countscross-source searchone-click launchcopy App IDopen install folderopen Wine prefix

Quick access

Library → type a game name in search

Library → Up/Down to move through the game list

Inside a game's detail

Game detail

Select a game to open its detail pane: KPI strip, a Launch button by the title, launch options and the compatibility tool

Capabilities

launch options editorquick presets (GameMode, NVIDIA dGPU, MangoHud, Proton Log), placed around %command%Proton / Wine tool dropdownHeroic toggles (Esync, Fsync, DXVK/VKD3D)ProtonDB tier + report count

Quick access

Library → select a game

launch options: gamemoderun mangohud %command%

Maintenance

Prefix and shader cache facts for the selected game, plus the folder actions - see inside compatdata without cd-ing into it

Capabilities

prefix size + created dateDXVK version (from d3d11.dll)VKD3D-Proton version (from d3d12.dll)shader cache size + Clear shader cache (Steam)open install folder / open prefixdelete prefix with confirmation

Quick access

Library → select a game → Maintenance → Open prefix

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

Launch check

Per-game tools dialog that lists the usual reasons a game won't start, each with what to do about it. Reads files and settings only; never starts the game

Capabilities

missing or doubled %command%wrapper tools not installedremoved Proton buildmissing anti-cheat runtimemissing install folderProtonDB rating as context

Quick access

Per-game tools → Launch check…

Proton log

Per-game tools dialog (Steam games) that shows the end of steam-<appid>.log, with a problems-only filter

Capabilities

problem-line filtercopyopen filelarge logs never loaded whole

Quick access

Per-game tools → Proton log…

ScopeBuddy and MangoHud overrides

Per-game tools dialogs (Steam games) for a per-app scb.conf.d override and a per-game MangoHud config

Capabilities

ScopeBuddy per-app overrideMangoHud per-game config

Quick access

Per-game tools → ScopeBuddy override…

Per-game tools → MangoHud override…

Winetricks

Per-game tools dialog that runs Protontricks for the game: quick-run common verbs or open its full GUI

Capabilities

common verbsopen the Protontricks GUInative or Flatpak Protontricks

Quick access

Per-game tools → Winetricks…

Known fixes

Per-game tools dialog (Steam games) with the game fixes database - known fixes per App ID plus universal fixes

Capabilities

env vars and/or launch argumentsAdd to launch optionsuser-contributed fixes

Quick access

Per-game tools → Known fixes…

~/.config/protonshift/fixes/

Profiles

Per-game tools dialog (Steam games): save a complete game setup as a named profile; apply it later or to a different game

Capabilities

captures launch options + compat tool + env vars + power profileapply / export / delete per profileexport / import JSON bundles

Quick access

Per-game tools → Profiles… → Save current

Per-game tools → Profiles… → Export all… → protonshift-profiles.json

Save backups

Per-game tools dialog (Steam games): detected save folders are zipped into timestamped backups; restores go to a safe folder

Capabilities

Proton prefix + Steam userdata detectionper-folder sizesBack up nowbrowse + restore previous backups

Quick access

Per-game tools → Save backups… → Back up now

~/.config/protonshift/backups/

Capabilities

size, version, in-use-by gamessha512-verified installcancellable progresssafe remove with in-use warningopen folder

Quick access

Proton builds → Install GE-Proton11-7

Proton builds → Remove → confirm

Capabilities

720p/1080p/1440p/4K quick buttonsFPS limiterFSR + sharpness sliderHDR / fullscreen / borderlesslive command previewadd to the selected game's launch optionsdistro install hints

Quick access

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

Capabilities

target selector + recommendationmanaged block in shell filescopy as Steam launch optionsProton NVIDIA / AMD presetsDXVK / VKD3D tuningWayland compatibilityProton debug flags

Quick access

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

~/.xsessionrc # Cinnamon / XFCE / MATE on LightDM

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

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

xrandr (X11) / hyprctl (Hyprland, Lua config too) / wlr-randr / kscreen-doctorresolution + refresh-rate dropdowns per outputApply + Refresh15 second keep-or-revert dialog

Quick access

Displays → pick a mode → Apply → Keep

Capabilities

NVIDIA via nvidia-smi, AMD/Intel via DRM sysfsGPU name, driver, VRAM size, temperature (AMD/Intel: kernel driver and temperature)performance / balanced / battery saversystem76-power + powerprofilesctlflatpak-spawn --host inside the Flatpak

Quick access

System → Power profile → Performance

System → Refresh

Capabilities

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

Quick access

Controllers → Test gamepad

Capabilities

system / dark / lightProton Neon / Phosphor Console / Soft Glass / Deepslate8 accent presets, any hex, or a color pickerinterface sounds: Pulse / Glass / Terminal + volumeProtonDB lookups toggleAbout: version, Check for updates, app folders

Quick access

Settings → Appearance → Accent → #8b5cf6

Settings → About → Check for updates

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

Install from the signed I4C Flatpak repository (see Install above) - add it once and updates arrive with flatpak update. Tagged GitHub releases attach a prebuilt .flatpak bundle built by CI, and the manifest under flatpak/ builds locally.

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 game won't start, or closes right after launch

Select it in Library and open Per-game tools, Launch check (v1.3.0+). It lists the usual causes - launch options with no %command% or two of them, a wrapper tool that isn't installed, a removed Proton build, a missing anti-cheat runtime or install folder - with what to do about each. If that comes up clean, Per-game tools, Proton log turns on PROTON_LOG=1; launch once, then read steam-<appid>.log there, filtered to the lines that look like problems.

A launch preset or known fix was added but does nothing

Before v1.3.0, presets and fixes were appended to the end of the line, so on a line without %command% they became game arguments. Update to 1.3.0 or later, where they are placed around %command%, and re-apply the preset.

GE-Proton from my distro's package isn't listed (Flatpak)

Before v1.3.1 the Flatpak could not see builds a distro package installs system-wide, such as proton-ge-custom-bin in /usr/share/steam/compatibilitytools.d, so they were missing from the Proton builds page and the per-game Proton picker. Update to 1.3.1 or later. Builds in your own compatibilitytools.d folder were always listed.

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