Steam Proton Helper

A comprehensive Linux tool designed to streamline the setup and troubleshooting of Steam and Proton for gaming on Linux. This helper application automatically detects missing dependencies, validates system configurations, and provides actionable fixes to eliminate common barriers that prevent Windows games from running smoothly on Linux.

Note: This tool is a read-only checker by default. Use --apply to auto-install missing packages.

Purpose

SteamProtonHelper serves as your first-line diagnostic and setup assistant for Linux gaming. It bridges the gap between a fresh Linux installation and a gaming-ready system by:

Automated Detection: Identifying your Linux distribution and available package managers
Dependency Validation: Checking for all required gaming components (Steam, Proton, graphics drivers, libraries)
Smart Remediation: Providing distribution-specific commands to fix detected issues
System Verification: Ensuring compatibility layers and runtime environments are properly configured

Features

Steam Detection: Detects Native, Flatpak, and Snap Steam installations
Proton Detection: Finds official Proton and GE-Proton across all Steam libraries
Vulkan Verification: Validates Vulkan support with actionable guidance
32-bit Support: Checks multilib/i386 packages required for Windows games
Multi-Library Support: Parses libraryfolders.vdf to check all Steam libraries
JSON Output: Machine-readable output for scripting and automation
No External Dependencies: Single-file Python script with stdlib only

Supported Configurations

Steam Installation Types

Type	Detection Method	Status
Native	`steam` in PATH	Full support
Flatpak	`flatpak info com.valvesoftware.Steam`	Full support
Snap	`snap list steam`	Best-effort

Linux Distributions

Distribution	Package Manager	32-bit Check
Ubuntu/Debian/Mint/Pop!_OS	apt	`dpkg --print-foreign-architectures`, per-package status
Fedora/RHEL/CentOS/Rocky	dnf	Automatic multilib, per-package status
Arch/Manjaro/EndeavourOS	pacman	`[multilib]` in pacman.conf, per-package status
openSUSE	zypper	Basic support

Quick Start

Prerequisites

Linux operating system (x86_64)
Python 3.8 or higher
Terminal access

Installation

Option 1: Install via pip (Recommended)

# CLI only
pip install steam-proton-helper

# CLI + GUI
pip install steam-proton-helper[gui]

# Or with pipx (for isolated install)
pipx install steam-proton-helper

Option 2: Clone and run directly

git clone https://github.com/AreteDriver/SteamProtonHelper.git
cd SteamProtonHelper
chmod +x steam_proton_helper.py

Option 3: Use the installation script

git clone https://github.com/AreteDriver/SteamProtonHelper.git
cd SteamProtonHelper
./install.sh

GUI

Steam Proton Helper includes a full PyQt6 GUI with three tabs:

System Checks: Visual tree view of all checks with status icons
Proton Management: Install/update GE-Proton versions
ProtonDB Lookup: Search game compatibility by name or AppID

# Launch GUI
steam-proton-helper-gui

Basic Usage

# Run all checks with colored output
./steam_proton_helper.py

# Or with Python directly
python3 steam_proton_helper.py

CLI Options

usage: steam_proton_helper.py [-h] [--version] [--json] [--no-color] [--verbose]
                              [--fix [FILE]] [--apply] [--dry-run] [--yes]
                              [--game NAME] [--search QUERY] [--list-proton]
                              [--install-proton VERSION] [--force]
                              [--remove-proton VERSION] [--update-proton]
                              [--check-updates] [--recommend GAME] [--list-games]
                              [--profile [ACTION]] [--profile-proton VERSION]
                              [--profile-options OPTIONS] [--profile-mangohud]
                              [--profile-gamemode] [--shader-cache [ACTION]]
                              [--compatdata [ACTION]] [--backup-dir DIR]
                              [--perf-tools] [--logs [TYPE]] [--log-lines N]

Steam Proton Helper - Check system readiness for Steam gaming on Linux.

Core Options:
  -h, --help            Show this help message and exit
  --version, -V         Show program's version number and exit
  --json                Output results as machine-readable JSON
  --no-color            Disable ANSI color codes in output
  --verbose, -v         Show verbose/debug output including paths tried

Fix & Install:
  --fix [FILE]          Generate a shell script with fix commands (stdout or file)
  --apply               Auto-install missing packages (prompts for confirmation)
  --dry-run             Show what --apply would install without executing
  --yes, -y             Skip confirmation prompt (use with --apply)

ProtonDB & Game Search:
  --game NAME           Check ProtonDB compatibility by game name or AppID
  --search QUERY        Search Steam for games (returns AppIDs, no ProtonDB lookup)
  --recommend GAME      Recommend best Proton version based on ProtonDB reports
  --list-games          List installed Steam games with their Proton versions

Proton Management:
  --list-proton         List all detected Proton installations
  --install-proton VERSION  Install GE-Proton (use "latest" or "list")
  --remove-proton VERSION   Remove a custom Proton version
  --update-proton       Update all GE-Proton versions to latest
  --check-updates       Check if newer GE-Proton versions are available
  --force               Force reinstall if already installed

Game Profiles:
  --profile [ACTION]    Manage launch profiles: list, get, set, delete
  --profile-proton VERSION   Proton version for profile
  --profile-options OPTIONS  Launch options for profile
  --profile-mangohud    Enable MangoHud for profile
  --profile-gamemode    Enable GameMode for profile

Maintenance:
  --shader-cache [ACTION]    Manage shader caches: list, clear <appid|all>
  --compatdata [ACTION]      Manage Wine prefixes: list, backup, restore, backups
  --backup-dir DIR           Directory for compatdata backups
  --perf-tools               Check status of gaming performance tools
  --logs [TYPE]              View logs: all, errors, steam, proton, dxvk
  --log-lines N              Number of log entries to show (default: 50)

Examples

# Standard check with colored output
./steam_proton_helper.py

# JSON output for scripting
./steam_proton_helper.py --json

# Generate fix script to stdout
./steam_proton_helper.py --fix

# Generate fix script to file
./steam_proton_helper.py --fix fix-steam.sh
# Then review and run: bash fix-steam.sh

# Preview what packages would be installed
./steam_proton_helper.py --dry-run

# Auto-install missing packages (with confirmation prompt)
./steam_proton_helper.py --apply

# Auto-install without confirmation (for scripting)
./steam_proton_helper.py --apply --yes

# Verbose mode to see all paths checked
./steam_proton_helper.py --verbose

# Disable colors (useful for piping)
./steam_proton_helper.py --no-color

# Combine options
./steam_proton_helper.py --json 2>/dev/null | jq '.summary'

# Check ProtonDB compatibility by game name
./steam_proton_helper.py --game "elden ring"
./steam_proton_helper.py --game "The Witcher 3: Wild Hunt"

# Or by Steam AppID
./steam_proton_helper.py --game 292030    # The Witcher 3
./steam_proton_helper.py --game 1245620   # Elden Ring

# Check multiple games at once
./steam_proton_helper.py --game "elden ring" --game "baldurs gate 3"
./steam_proton_helper.py --game "292030,1245620"  # Comma-separated AppIDs

# Get ProtonDB info as JSON
./steam_proton_helper.py --game "elden ring" --json
./steam_proton_helper.py --game 292030 --game 1245620 --json  # Batch JSON

# Search Steam for games (get AppIDs without ProtonDB lookup)
./steam_proton_helper.py --search "witcher"
./steam_proton_helper.py --search "souls" --json

# List all installed Proton versions
./steam_proton_helper.py --list-proton
./steam_proton_helper.py --list-proton --verbose  # Show full paths
./steam_proton_helper.py --list-proton --json     # JSON output

# Install GE-Proton
./steam_proton_helper.py --install-proton list    # See available versions
./steam_proton_helper.py --install-proton latest  # Install latest
./steam_proton_helper.py --install-proton GE-Proton10-26  # Specific version
./steam_proton_helper.py --install-proton latest --force  # Reinstall

Exit Codes

Code	Meaning
0	All checks passed (may have warnings)
1	One or more checks failed
130	Interrupted by user (Ctrl+C)

Shell Completions

Tab completion is available for Bash, Zsh, and Fish. Install via ./install.sh or manually:

Bash:

cp completions/steam-proton-helper.bash ~/.local/share/bash-completion/completions/steam-proton-helper

Zsh: (add ~/.zsh/completions to your $fpath in .zshrc)

mkdir -p ~/.zsh/completions
cp completions/_steam-proton-helper ~/.zsh/completions/

Fish:

cp completions/steam-proton-helper.fish ~/.config/fish/completions/

What It Checks

System

Linux distribution and package manager
System architecture (x86_64 recommended)

Steam

Steam client installation (native/flatpak/snap)
Steam root directory location
Steam library folders (from libraryfolders.vdf)

Proton

Official Proton installations in steamapps/common
GE-Proton and custom Proton in compatibilitytools.d
Validates presence of proton executable, toolmanifest.vdf, or version file

Graphics

Vulkan: Runs vulkaninfo and checks exit code
OpenGL: Runs glxinfo -B if available

ProtonDB Integration

Use --game to check game compatibility on ProtonDB. You can search by name or AppID:

# Search by game name
./steam_proton_helper.py --game "elden ring"

# Or use Steam AppID directly
./steam_proton_helper.py --game 292030

Output:

Found: ELDEN RING (AppID: 1245620)

ProtonDB Compatibility for AppID 1245620
────────────────────────────────────────────
  🥇 Rating: GOLD
  📊 Score: 0.77
  📝 Reports: 1935
  🎯 Confidence: strong
  ⭐ Best Reported: PLATINUM
  📈 Trending: PLATINUM

  ℹ️  Runs perfectly after tweaks

  🔗 https://www.protondb.com/app/1245620

If multiple games match your search, you'll see a list:

Multiple games found for 'witcher':

  1. The Witcher 3: Wild Hunt (AppID: 292030)
  2. The Witcher 2: Assassins of Kings (AppID: 20920)
  3. The Witcher: Enhanced Edition (AppID: 20900)

Use --game <AppID> for the specific game.

32-bit / Multilib

Architecture support enabled (i386/multilib)
Per-package status for critical 32-bit libraries:
- apt: libc6-i386, libstdc++6:i386, libvulkan1:i386, mesa-vulkan-drivers:i386
- pacman: lib32-glibc, lib32-gcc-libs, lib32-vulkan-icd-loader, lib32-mesa
- dnf: glibc.i686, libgcc.i686, libstdc++.i686, vulkan-loader.i686

Example Output

╔══════════════════════════════════════════╗
║   Steam + Proton Helper for Linux        ║
╚══════════════════════════════════════════╝

Checking Steam and Proton dependencies...

── System ──
  ✓ Linux Distribution: Ubuntu 24.04.1 LTS
  ✓ 64-bit System: x86_64 architecture

── Steam ──
  ✓ Steam Client: Installed: Native Steam in PATH
  ✓ Steam Root: /home/user/.local/share/Steam

── Proton ──
  ✓ Proton: Found 3 installation(s)

── Graphics ──
  ✓ Vulkan Support: Vulkan is available
  ✓ Mesa/OpenGL: OpenGL support available

── 32-bit ──
  ✓ Multilib/32-bit: i386 architecture enabled
  ✓ libc6-i386: Installed
  ✓ libstdc++6:i386: Installed
  ✓ libvulkan1:i386: Installed
  ✓ mesa-vulkan-drivers:i386: Installed

────────────────────────────────────────────
Summary
  Passed:   12
  Failed:   0
  Warnings: 0

✓ Your system is ready for Steam gaming!

Tips:
  • Enable Proton in Steam: Settings → Compatibility → Enable Steam Play
  • Keep graphics drivers updated for best performance
  • Check game compatibility at protondb.com

JSON Output Format

{
  "system": {
    "distro": "Ubuntu 24.04.1 LTS",
    "package_manager": "apt",
    "arch": "x86_64"
  },
  "steam": {
    "variant": "native",
    "message": "Native Steam in PATH",
    "root": "/home/user/.local/share/Steam",
    "libraries": ["/home/user/.local/share/Steam", "/mnt/games/SteamLibrary"]
  },
  "proton": {
    "found": true,
    "installations": [
      {
        "name": "Proton 9.0",
        "path": "/home/user/.local/share/Steam/steamapps/common/Proton 9.0",
        "has_executable": true,
        "has_toolmanifest": true,
        "has_version": true
      }
    ]
  },
  "checks": [...],
  "summary": {
    "passed": 12,
    "failed": 0,
    "warnings": 0,
    "skipped": 0
  }
}

Common Issues and Fixes

Steam Not Installed

Ubuntu/Debian:

sudo apt update && sudo apt install -y steam

Fedora:

sudo dnf install -y steam

Arch Linux:

sudo pacman -S --noconfirm steam

Missing Vulkan Support

If vulkaninfo fails, check:

GPU drivers are installed correctly
Vulkan ICD files exist (/usr/share/vulkan/icd.d/)
32-bit Vulkan libraries are installed

Ubuntu/Debian:

sudo apt install -y vulkan-tools mesa-vulkan-drivers libvulkan1:i386

Fedora:

sudo dnf install -y vulkan-tools mesa-vulkan-drivers vulkan-loader.i686

Arch Linux:

sudo pacman -S --noconfirm vulkan-tools vulkan-icd-loader lib32-vulkan-icd-loader

32-bit Support Not Enabled

Ubuntu/Debian:

sudo dpkg --add-architecture i386
sudo apt update
sudo apt install -y libc6-i386 libstdc++6:i386 libvulkan1:i386

Arch Linux: Enable [multilib] in /etc/pacman.conf:

sudo sed -i '/\[multilib\]/,/Include/s/^#//' /etc/pacman.conf
sudo pacman -Sy
sudo pacman -S --noconfirm lib32-glibc lib32-gcc-libs

Proton Not Found

Open Steam
Go to Settings → Compatibility
Enable "Enable Steam Play for supported titles"
Optionally enable "Enable Steam Play for all other titles"
Select your preferred Proton version
Restart Steam

Troubleshooting

Script won't run

# Check Python version
python3 --version  # Requires 3.8+

# Make executable
chmod +x steam_proton_helper.py

# Run directly
python3 steam_proton_helper.py

Steam installed but not detected

For Flatpak: Ensure flatpak command is available
For native: Check if steam is in your PATH
Run with --verbose to see detection attempts

VDF parsing fails

The script includes a minimal VDF parser. If libraryfolders.vdf has an unusual format:

Run with --verbose to see parsing details
The script will fall back to default paths

Custom Proton Versions

Steam Proton Helper automatically detects custom Proton builds installed in compatibilitytools.d. Here's how to install and manage them.

Installing GE-Proton (Recommended)

GE-Proton is the most popular custom Proton build with additional patches and fixes.

Manual Installation:

# Create the compatibility tools directory
mkdir -p ~/.steam/root/compatibilitytools.d

# Download latest GE-Proton (check GitHub for current version)
cd /tmp
wget https://github.com/GloriousEggroll/proton-ge-custom/releases/download/GE-Proton9-22/GE-Proton9-22.tar.gz

# Extract to Steam's compatibility tools directory
tar -xzf GE-Proton9-22.tar.gz -C ~/.steam/root/compatibilitytools.d/

# Restart Steam to detect the new Proton version

Using ProtonUp-Qt (Easier):

# Install ProtonUp-Qt
flatpak install flathub net.davidotek.pupgui2

# Run and select GE-Proton versions to install
flatpak run net.davidotek.pupgui2

Custom Proton Locations

Steam looks for custom Proton builds in these directories:

Steam Type	Path
Native	`~/.steam/root/compatibilitytools.d/`
Native (alt)	`~/.local/share/Steam/compatibilitytools.d/`
Flatpak	`~/.var/app/com.valvesoftware.Steam/data/Steam/compatibilitytools.d/`

Other Custom Proton Builds

Build	Description	Link
GE-Proton	Patches for better game compatibility	GitHub
Proton-TKG	Highly configurable, build-your-own	GitHub
Proton Experimental	Valve's bleeding-edge builds	Steam Library → Tools

Selecting Proton Version Per-Game

Right-click the game in Steam → Properties
Go to Compatibility tab
Check "Force the use of a specific Steam Play compatibility tool"
Select your preferred Proton version from the dropdown

Steam Launch Options

Launch options let you customize how games run. Set them via: Right-click game → Properties → General → Launch Options

Common Launch Options

Option	Description
`PROTON_USE_WINED3D=1 %command%`	Use OpenGL instead of Vulkan (for older GPUs)
`PROTON_NO_ESYNC=1 %command%`	Disable esync (fixes some crashes)
`PROTON_NO_FSYNC=1 %command%`	Disable fsync (fixes some crashes)
`DXVK_HUD=fps %command%`	Show FPS counter
`DXVK_HUD=full %command%`	Show full DXVK stats overlay
`mangohud %command%`	Use MangoHud overlay (if installed)
`gamemoderun %command%`	Enable GameMode optimizations (if installed)
`PROTON_LOG=1 %command%`	Enable Proton logging for debugging
`WINEDEBUG=-all %command%`	Suppress Wine debug output

Performance Launch Options

# Maximum performance (combine as needed)
gamemoderun mangohud %command%

# For AMD GPUs - enable ACO shader compiler
RADV_PERFTEST=aco %command%

# Limit FPS to reduce heat/power
DXVK_FRAME_RATE=60 %command%

# Use specific GPU (multi-GPU systems)
DRI_PRIME=1 %command%

Troubleshooting Launch Options

# Game crashes on startup - try disabling sync
PROTON_NO_ESYNC=1 PROTON_NO_FSYNC=1 %command%

# Black screen or rendering issues
PROTON_USE_WINED3D=1 %command%

# Enable verbose logging
PROTON_LOG=1 WINEDEBUG=+loaddll %command%

# Skip launcher/intro videos (game-specific)
%command% -skipintro -novid

Game-Specific Examples

# Elden Ring - common fixes
PROTON_NO_FSYNC=1 %command%

# Cyberpunk 2077 - performance mode
gamemoderun mangohud DXVK_ASYNC=1 %command%

# Older DirectX 9 games
PROTON_USE_WINED3D=1 %command%

# Unity games with cursor issues
PROTON_USE_WINED3D=1 %command%

Environment Variables Reference

Variable	Values	Description
`PROTON_USE_WINED3D`	0/1	Use OpenGL instead of DXVK
`PROTON_NO_ESYNC`	0/1	Disable eventfd-based synchronization
`PROTON_NO_FSYNC`	0/1	Disable futex-based synchronization
`PROTON_FORCE_LARGE_ADDRESS_AWARE`	0/1	Force LAA for 32-bit games
`PROTON_OLD_GL_STRING`	0/1	Use old OpenGL version string
`PROTON_ENABLE_NVAPI`	0/1	Enable NVAPI for NVIDIA features
`DXVK_HUD`	fps/full/off	DXVK overlay settings
`DXVK_ASYNC`	0/1	Async shader compilation (reduces stutter)
`DXVK_FRAME_RATE`	number	Limit framerate
`MANGOHUD`	0/1	Enable MangoHud overlay
`WINE_FULLSCREEN_FSR`	0/1	Enable AMD FSR upscaling
`WINE_FULLSCREEN_FSR_STRENGTH`	0-5	FSR sharpening (0=max, 5=min)

Advanced Features (v2.3+)

Game Launch Profiles

Create per-game launch profiles to store Proton versions and launch options:

# List all saved profiles
./steam_proton_helper.py --profile list

# Get profile for a specific game
./steam_proton_helper.py --profile get 1245620

# Set a profile with Proton version and options
./steam_proton_helper.py --profile set 1245620 \
  --profile-proton "GE-Proton9-22" \
  --profile-options "DXVK_ASYNC=1 %command%" \
  --profile-mangohud --profile-gamemode

# Delete a profile
./steam_proton_helper.py --profile delete 1245620

Profiles are stored in ~/.config/steam-proton-helper/profiles.json.

Shader Cache Management

Manage GPU shader caches to free disk space or fix shader-related issues:

# List shader caches with sizes
./steam_proton_helper.py --shader-cache list

# Clear shader cache for a specific game
./steam_proton_helper.py --shader-cache clear 1245620

# Clear all shader caches (use with caution)
./steam_proton_helper.py --shader-cache clear all

Supports both AMD (mesa) and NVIDIA shader cache locations.

Compatdata (Wine Prefix) Backup & Restore

Backup and restore game Wine prefixes to preserve saves and settings:

# List all compatdata directories with sizes
./steam_proton_helper.py --compatdata list

# Backup a game's Wine prefix
./steam_proton_helper.py --compatdata backup 1245620

# List existing backups
./steam_proton_helper.py --compatdata backups

# Restore from backup
./steam_proton_helper.py --compatdata restore 1245620

# Use custom backup directory
./steam_proton_helper.py --compatdata backup 1245620 --backup-dir /mnt/backup/steam

Backups are compressed with gzip and stored in ~/.local/share/steam-proton-helper/backups/ by default.

Installed Games List

View all installed Steam games and their configured Proton versions:

# List installed games
./steam_proton_helper.py --list-games

# JSON output for scripting
./steam_proton_helper.py --list-games --json

Parses ACF manifest files to detect installed games across all Steam libraries.

Performance Tools Status

Check if gaming performance tools are installed and available:

# Check performance tools
./steam_proton_helper.py --perf-tools

Checks for: GameMode, MangoHud, vkBasalt, libstrangle, and OBS Game Capture.

Log Viewer

View and filter Steam/Proton logs for troubleshooting:

# View all recent log entries
./steam_proton_helper.py --logs

# View only errors
./steam_proton_helper.py --logs errors

# View specific log type
./steam_proton_helper.py --logs steam
./steam_proton_helper.py --logs proton
./steam_proton_helper.py --logs dxvk

# Limit number of entries
./steam_proton_helper.py --logs errors --log-lines 100

Proton Version Recommendations

Get Proton version recommendations based on ProtonDB reports:

# Get recommended Proton for a game
./steam_proton_helper.py --recommend "elden ring"
./steam_proton_helper.py --recommend 1245620

Analyzes ProtonDB reports to suggest the most successful Proton versions for each game.

Resources

License

This project is open source and available under the MIT License.

Disclaimer

This tool is provided as-is for informational purposes. It does not install packages by default (use --apply to enable). Always review what will be installed with --dry-run before using --apply.

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github		.github
assets		assets
completions		completions
gui		gui
resources		resources
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT_READINESS.md		DEPLOYMENT_READINESS.md
EXAMPLES.md		EXAMPLES.md
LICENSE		LICENSE
MAINTAINER_GUIDE.md		MAINTAINER_GUIDE.md
MANIFEST.in		MANIFEST.in
README.md		README.md
install.sh		install.sh
pyproject.toml		pyproject.toml
requirements-gui.txt		requirements-gui.txt
requirements.txt		requirements.txt
setup.py		setup.py
steam-proton-helper.desktop		steam-proton-helper.desktop
steam_proton_helper.py		steam_proton_helper.py
steam_proton_helper_gui.py		steam_proton_helper_gui.py
test_steam_proton_helper.py		test_steam_proton_helper.py
uninstall.sh		uninstall.sh

Uh oh!

License

AreteDriver/SteamProtonHelper

Folders and files

Latest commit

History

Repository files navigation

Steam Proton Helper

Purpose

Features

Supported Configurations

Steam Installation Types

Linux Distributions

Quick Start

Prerequisites

Installation

Option 1: Install via pip (Recommended)

Option 2: Clone and run directly

Option 3: Use the installation script

GUI

Basic Usage

CLI Options

Examples

Exit Codes

Shell Completions

What It Checks

System

Steam

Proton

Graphics

ProtonDB Integration

32-bit / Multilib

Example Output

JSON Output Format

Common Issues and Fixes

Steam Not Installed

Missing Vulkan Support

32-bit Support Not Enabled

Proton Not Found

Troubleshooting

Script won't run

Steam installed but not detected

VDF parsing fails

Custom Proton Versions

Installing GE-Proton (Recommended)

Custom Proton Locations

Other Custom Proton Builds

Selecting Proton Version Per-Game

Steam Launch Options

Common Launch Options

Performance Launch Options

Troubleshooting Launch Options

Game-Specific Examples

Environment Variables Reference

Advanced Features (v2.3+)

Game Launch Profiles

Shader Cache Management

Compatdata (Wine Prefix) Backup & Restore

Installed Games List

Performance Tools Status

Log Viewer

Proton Version Recommendations

Resources

License

Disclaimer

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 14

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 3

Packages