Skip to content
    Back to home
    Documentation

    Getting Started

    Download, 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

    Grab the package for your distro from GitHub Releases. The AppImage is one binary for every distro — official builds bundle a portable CPython 3.12 runtime and the full backend stack, so nothing leaks into your system packages:

    AppImage (any distro)
    $ chmod +x ProtonShift-*.AppImage && ./ProtonShift-*.AppImage
    .deb (Ubuntu / Pop!_OS / Mint)
    $ sudo dpkg -i protonshift_*_amd64.deb
    .rpm (Fedora / openSUSE / RHEL)
    $ sudo dnf install ProtonShift-*.rpm
    Flatpak
    $ flatpak install ProtonShift-*.flatpak && flatpak run io.github.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:

    1. Press Ctrl+K and type a game name to jump straight to it.
    2. Open the launch options editor and flip a quick preset — GameMode, NVIDIA dGPU, MangoHud, or Proton Log. Presets grey out with a hint if their tool isn't installed.
    3. Pick a Proton or Wine version from the dropdown instead of hunting through config files.
    4. 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 Steam and Heroic launch options, with quick presets for GameMode, NVIDIA dGPU offload, MangoHud, and Proton logging.

    Gamescope

    Build the full gamescope command with resolution pickers, FPS limit, FSR sharpness, HDR, and a live preview. Insert or copy in one click.

    ScopeBuddy

    Edit the global scb.conf and per-app overrides under scb.conf.d/ with a KV editor. Detection toasts flag missing or shadowed installs.

    MangoHud

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

    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, creation date, 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 temps and VRAM (nvidia-smi / DRM sysfs), power profile switching, display detection on X11 and Wayland, shader cache totals.

    Controllers

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

    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

    ~/.config/MangoHud/MangoHud.conf (+ wine-<game>.conf per game)
    fps_limit=144
cpu_temp
gpu_temp
frame_timing
position=top-left
toggle_hud=Shift_R+F12

    ScopeBuddy

    ~/.config/scopebuddy/scb.conf (+ scb.conf.d/<appid>.conf overrides)
    SCB_GAMESCOPE_ARGS="-W 2560 -H 1440 -r 144 -f"
SCB_AUTO_RES=1
SCB_AUTO_HDR=1
SCB_AUTO_VRR=1

    Environment variables

    ~/.config/environment.d/protonshift.conf
    # Applied at login, survives reboots
DXVK_ASYNC=1
PROTON_ENABLE_NVAPI=1
__GL_SHADER_DISK_CACHE_SKIP_CLEANUP=1

    ProtonShift itself

    ~/.config/protonshift/
    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, all a Ctrl+K away.

    Library

    Your entire collection in one searchable list — Steam, Heroic (Epic + GOG), and Lutris, native and Flatpak

    Capabilities

    source badgesper-source countscross-source searchlaunch via steam:// / heroic://copy App IDopen install folderopen Wine prefix

    Quick access

    Ctrl+K → type a game name → Enter

    Game Detail

    Per-game hub: KPI strip, tabs, and a profiles menu for everything ProtonShift knows about one game

    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%

    Gamescope

    Visual command builder — resolutions, FPS limit, FSR sharpness, HDR, integer scaling — with a live preview

    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%

    ScopeBuddy

    First-class editor for ScopeBuddy's global scb.conf and per-app overrides, with detection toasts

    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

    MangoHud

    Visual editor for the overlay — global config plus auto-discovered per-game wine-<game>.conf files

    Capabilities

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

    Quick access

    ~/.config/MangoHud/MangoHud.conf

    Environment

    Global gaming env vars that persist across reboots via ~/.config/environment.d/, with explained presets

    Capabilities

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

    Quick access

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

    Profiles

    Save a complete game setup as a named profile; restore it later or apply it to a different game

    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

    Prefixes

    Wine/Proton prefix inspector — see inside compatdata without cd-ing into it

    Capabilities

    prefix size + creation dateDXVK version (from d3d11.dll)VKD3D-Proton version (from d3d12.dll)open in file managerdelete with confirmation

    Quick access

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

    Saves

    Save backup & restore — auto-detected locations, timestamped ZIPs, one-click restore

    Capabilities

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

    Quick access

    ~/.config/protonshift/backups/

    Fixes

    Game fixes database — known fixes per App ID plus universal fixes, applied in one click

    Capabilities

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

    Quick access

    ~/.config/protonshift/fixes/

    System

    Hardware dashboard — GPU, power profiles, displays, and shader cache totals

    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

    Controllers

    Controller detection plus a live gamepad tester with rumble

    Capabilities

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

    Quick access

    Controllers → Test gamepad

    Speed

    Keyboard shortcuts

    The command palette is the fastest way around the app.

    Ctrl+K

    Open the command palette from anywhere — jump between pages, focus the game search, or trigger common actions.

    Esc

    Close the command palette.

    Ctrl+K → game name

    Search your whole library — Steam, Heroic, and Lutris results together — and jump straight to the game.

    Ctrl+K → "gamescope"

    Jump to the Gamescope command builder without touching the mouse.

    Ctrl+K → "mangohud"

    Open the MangoHud visual editor.

    Ctrl+K → "system"

    Check GPU temps, VRAM, and power profiles on the System dashboard.

    When things break

    Troubleshooting

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

    AppImage fails to start on Python 3.13 distros (CachyOS, Arch) with ModuleNotFoundError: pydantic_core

    Fixed in v0.9.0 — the vendored native extensions were built for Python 3.12, and the compat layer now falls back to system packages in memory (v0.8.11's delete-based fix was a no-op on read-only squashfs). Update to the latest release; if you must stay on an older build, install python3-pydantic from your distro.

    Packaged build renders as unstyled raw HTML

    Fixed in v0.9.7 — the internal static server was 403'ing Turbopack's dot-heavy hashed CSS filenames as path-traversal attempts. Update to v0.9.7 or later.

    Gamescope / MangoHud / GameMode show "Not Installed" on Bazzite, Kinoite, Silverblue, or SteamOS

    Fixed in v0.8.9 — tool detection now checks immutable-distro bin directories (/var/usrlocal/bin, NixOS paths) and tool-specific known paths beyond PATH. On Bazzite and SteamOS most of these tools are pre-installed.

    App window never appears

    Run the binary from a terminal (e.g. /opt/ProtonShift/protonshift or the AppImage directly) and check stderr for [python] lines — the backend logs why it exited. Official builds bundle CPython 3.12 and the full API stack, so no host Python packages are required.

    Calling the backend API directly returns 401

    Since v0.9.0 every endpoint (except /health and /docs) requires per-launch bearer-token auth. Send Authorization: Bearer <token>; Electron exposes the token to the backend via PROTONSHIFT_API_TOKEN at launch.

    Still stuck? Open an issue — include the [python] stderr lines if the backend is involved.

    AGPL-3.0

    Contributing

    PRs are welcome. The full contributor guide — architecture, project layout, build instructions, VM testing harness, and release process — lives in ARCHITECTURE.md.

    build from source
    # Backend
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -e ".[dev]"
$ pytest -q

# Full Electron app
$ cd electron && pnpm install && pnpm dev

    96+ backend tests, ruff and pyright clean, and packaged builds are exercised in VMs across six distros before every release. Start with ARCHITECTURE.md.

    Ready to shift into gear?

    Explore featuresView changelog