Debian-Based Gaming Setup Script

Transform your Debian-based Linux system into a complete gaming powerhouse

Full Documentation Wiki — detailed guides on utility, setup, execution and troubleshooting.

📋 Table of Contents

Supported Operating Systems
What's New
Quick Start
Key Features
Installed Components
Hardware Support
Usage Examples
Command-Line Options
Rollback System
Full Uninstall
Post-Installation
File Locations
Documentation
Troubleshooting
Contributing
Project Stats
License
Support

🖥️ Supported Operating Systems

Distribution	Versions	Status	Base	Notes
	22.04, 24.04	✅ Tested	—	Primary target, all editions
	21.x, 22.x	✅ Tested	Ubuntu	Cinnamon, XFCE, MATE
	6	✅ Tested	Debian	Debian-based Mint
	22.04, 24.04	✅ Tested	Ubuntu	System76 derivative
	17	✅ Tested	Ubuntu	Pro & Core editions
	12 (Bookworm)	✅ Tested	—	Stable only
	Rolling	✅ Tested	Debian	Maps to Debian codename
	7 (Horus)	⚡ Compatible	Ubuntu 22.04	Pantheon desktop
	User Edition	⚡ Compatible	Ubuntu 22.04	KDE Plasma 6
Other derivatives	—	⚡ Compatible	Debian/Ubuntu	Via 7-step ID_LIKE fallback

Requirements: Python 3.12+ · root/sudo · internet · 5+ GB disk · x86_64

⬆ Back to top

🌟 What's New

v3.4.4 — CI/CD Overhaul & Node 24 Migration

🔄 All GitHub Actions upgraded to v6 — Node 24 compatible, eliminates deprecation warnings
🧪 8 lint checks — Added f-string logging detection, test count regression guard, subprocess timeout verification
🚀 Full release workflow — Automated GitHub Releases with 3 archive formats and auto-generated notes
📊 Pipeline summary — GITHUB_STEP_SUMMARY tables for every run

v3.4.3 — Wiki Expansion & Version Automation

📖 15 wiki pages (3,920 lines) — Launcher Guide, Setup Guide, expanded Architecture, Troubleshooting, and more
🔧 make version-bump — Single command syncs version across all files (11 patterns)

v3.4.1–v3.4.2 — Audit Remediation & Bug Fixes

🐛 3 runtime bugs fixed — Mixed logging format TypeError, AMD GPU false detection, GE-Proton dry-run checksum
🧪 136 tests — 100% critical method coverage (was 19%)
🔒 20 f-string logging calls eliminated — All converted to lazy %-formatting

v3.4.0 — Project Infrastructure

🏗️ GitHub infrastructure — FUNDING.yml, issue templates, PR template, .gitignore, LICENSE
🔧 Makefile — 43+ targets across 9 categories

Full changelog

⬆ Back to top

🚀 Quick Start

One-Command Installation

# Download
wget https://raw.githubusercontent.com/Sandler73/Debian-Gaming-Setup-Project/main/debian_gaming_setup.py

# Interactive installation
sudo python3 debian_gaming_setup.py

# Or use a preset for automated installation
sudo python3 debian_gaming_setup.py --preset standard -y

Presets

Preset	What's Included
`--preset minimal`	GPU drivers + Steam + essentials + 32-bit
`--preset standard`	Minimal + Lutris + Wine + GameMode + MangoHud + GE-Proton + codecs
`--preset complete`	Standard + Heroic + ProtonUp-Qt + Goverlay + vkBasalt + Waydroid + SOBER + Discord + Mumble + mods + optimizations
`--preset streaming`	Steam + MangoHud + GameMode + Discord + optimizations

Verify Before Installing

sudo python3 debian_gaming_setup.py --check-requirements  # Validate system
sudo python3 debian_gaming_setup.py --preset standard --dry-run  # Preview changes

⬆ Back to top

⭐ Key Features

Category	Feature	Details
🎮 Platforms	8 gaming platforms	Steam, Lutris, Heroic, ProtonUp-Qt, SOBER, Waydroid, Discord, OBS
🖥️ GPU	All vendors	NVIDIA, AMD, Intel — fully dynamic detection and driver selection
🖱️ VM	6 hypervisors	VMware, VirtualBox, KVM, Hyper-V, Xen, Parallels
⚡ Performance	5 tools	GameMode, MangoHud, Goverlay, vkBasalt, GreenWithEnvy
🔄 Rollback	7 action types	APT, Flatpak, repos, files, sysctl, GE-Proton — LIFO reversal
🗑️ Uninstall	Full removal	Categorized inventory, reverse-dependency order, confirmation gates
📋 CLI	43 arguments	9 groups, 4 presets, dry-run, auto-yes
🔒 Security	Audited	STRIDE model, CWE/SANS Top 25, no shell=True, no eval
🧪 Testing	136 tests	Unit, integration, security, host safety
🔧 CI/CD	4 jobs	Lint, test (3.12+3.13), security scan, release

⬆ Back to top

📦 Installed Components

Gaming Platforms & Launchers

Component	Package	Install Method	Pre-Detection
Steam	`steam` / `steam-installer`	APT	✅ version + update
Lutris	`lutris` / `net.lutris.Lutris`	APT / Flatpak	✅ version + update
Heroic Games Launcher	`com.heroicgameslauncher.hgl`	Flatpak	✅ version + update
ProtonUp-Qt	`net.davidotek.pupgui2`	Flatpak	✅ version + update
SOBER (Roblox)	`org.vinegarhq.Sober`	Flatpak	✅ version + update
Waydroid (Android)	`waydroid`	APT	✅ version + update

Compatibility Layers

Component	Package	Verification
Wine Staging	`winehq-staging`	WineHQ repo codename validation
Winetricks	`winetricks`	APT version check
GE-Proton	GitHub release	SHA512 checksum verification

Performance & Monitoring

Component	Package	Purpose
GameMode	`gamemode`	CPU/GPU optimization during gameplay
MangoHud	`mangohud` + `:i386`	FPS/performance HUD overlay
Goverlay	`goverlay`	MangoHud GUI configurator
vkBasalt	`vkbasalt`	Vulkan post-processing (sharpening, CAS)
GreenWithEnvy	`com.leinardi.gwe`	NVIDIA GPU fan curve and clock control
Performance Launcher	`~/launch-game.sh`	GameMode + MangoHud + CPU governor wrapper

Communication & Utilities

Component	Package	Install Method
Discord	`discord` / `com.discordapp.Discord`	APT / Flatpak
OBS Studio	`obs-studio` / `com.obsproject.Studio`	APT / Flatpak
Mumble	`mumble`	APT
r2modman	`com.thunderstore.r2modman`	Flatpak
Controller support	`xboxdrv`, `antimicrox`	APT

⬆ Back to top

🔩 Hardware Support

GPU Vendor	Detection	Driver Source	Features
NVIDIA	`lspci` + `ubuntu-drivers`	Dynamic version selection	Proprietary drivers, CUDA, Vulkan
AMD	`lspci`	Mesa + AMDGPU	Vulkan, 32-bit compatibility, firmware-aware
Intel	`lspci`	Mesa + i915	Media acceleration, Arc GPU support

VM Platform	Guest Tools	Auto-Detected
VMware	`open-vm-tools` + desktop	✅
VirtualBox	`virtualbox-guest-utils`	✅
KVM/QEMU	`qemu-guest-agent` + `spice-vdagent`	✅
Hyper-V	`hyperv-daemons`	✅
Xen	`xe-guest-utilities`	✅
Parallels	`parallels-tools`	✅

⬆ Back to top

🎯 Usage Examples

Complete Setups

# NVIDIA Gaming PC (Maximum Features)
sudo python3 debian_gaming_setup.py -y \
    --nvidia --all-platforms --sober --wine --ge-proton \
    --gamemode --mangohud --gwe --vkbasalt \
    --discord --obs --mod-managers --controllers \
    --essential --codecs --optimize --launcher

# AMD Gaming PC
sudo python3 debian_gaming_setup.py -y \
    --amd --all-platforms --wine --ge-proton \
    --gamemode --mangohud --vkbasalt \
    --discord --controllers --essential --codecs --optimize

# Intel Laptop (Battery-Conscious)
sudo python3 debian_gaming_setup.py -y \
    --intel --steam --lutris --wine \
    --gamemode --essential --codecs

Maintenance Operations

sudo python3 debian_gaming_setup.py --update           # Update installed components
sudo python3 debian_gaming_setup.py --rollback          # Undo last installation session
sudo python3 debian_gaming_setup.py --uninstall         # Full removal of all components
sudo python3 debian_gaming_setup.py --self-update       # Check for script updates
sudo python3 debian_gaming_setup.py --check-requirements # Validate system

⬆ Back to top

🎛️ Command-Line Options

Quick Reference

General:          --dry-run, --yes/-y, --verbose, --skip-update
GPU/Drivers:      --nvidia, --amd, --intel, --vm-tools
Platforms:        --steam, --lutris, --heroic, --protonup, --sober, --waydroid, --all-platforms
Compatibility:    --wine, --ge-proton
Performance:      --gamemode, --mangohud, --goverlay, --gwe, --vkbasalt, --optimize, --launcher
Communication:    --discord, --obs, --mumble
System:           --essential, --codecs, --32bit, --mod-managers, --controllers
Maintenance:      --rollback, --uninstall, --update, --self-update, --check-requirements, --cleanup
Presets:          --preset minimal|standard|complete|streaming

⬆ Back to top

🔄 Rollback System

Every reversible operation is automatically tracked. The rollback engine records 7 action types:

Action Type	What's Tracked	Reversal
`apt_install`	APT package installs	`apt-get remove`
`flatpak_install`	Flatpak app installs	`flatpak uninstall`
`repo_add`	Repository additions	Remove repo files + update
`file_create`	Files created by script	Remove file
`file_modify`	Files modified (backed up)	Restore from backup
`sysctl_write`	sysctl config changes	Remove + reload
`ge_proton_install`	GE-Proton extraction	Remove directory

sudo python3 debian_gaming_setup.py --rollback --dry-run  # Preview
sudo python3 debian_gaming_setup.py --rollback             # Execute

⬆ Back to top

🗑️ Full Uninstall

For complete removal of all gaming components installed by the script:

sudo python3 debian_gaming_setup.py --uninstall

The uninstall mode:

Scans for all installed gaming components (APT packages, Flatpak apps, GE-Proton, config files)
Displays a categorized inventory with versions
Confirms before proceeding
Removes in reverse dependency order (Flatpak → APT → autoremove → GE-Proton → configs → state)
Reports results with error details

This differs from --rollback which only undoes the last session. --uninstall finds all known components regardless of when they were installed.

⬆ Back to top

🎮 Post-Installation

Reboot — sudo reboot (required for GPU drivers)
Verify GPU — nvidia-smi or glxinfo | grep renderer
Configure Steam — Settings → Compatibility → Enable Steam Play → Proton Experimental
Test a game — Native: CS2, Portal 2 | Proton: Stardew Valley, Terraria
Performance launcher — ~/launch-game.sh steam

⬆ Back to top

📁 File Locations

File	Path	Purpose
Logs	`~/gaming_setup_logs/gaming_setup_*.log`	Timestamped operation logs
State	`~/gaming_setup_logs/installation_state.json`	Installed component inventory
Rollback	`~/gaming_setup_logs/rollback_manifest.json`	Action history for rollback
Backups	`~/gaming_setup_backups/`	Pre-modification file backups
Launcher	`~/launch-game.sh`	Performance game launcher
MangoHud	`~/.config/MangoHud/MangoHud.conf`	HUD overlay settings
vkBasalt	`~/.config/vkBasalt/vkBasalt.conf`	Post-processing config

⬆ Back to top

📖 Documentation

Document	Purpose	Best For
Wiki	Complete documentation hub (13 pages)	Everyone
Quick_Start.md	Step-by-step first-run guide	First-time users
Usage_Guide.md	Complete reference with all options	All users
FAQ.md	50+ questions across 12 categories	Quick answers
CHANGELOG.md	Version history from v1.0 to v3.4.2	Tracking changes
SECURITY.md	Security model and vulnerability reporting	Security researchers
CONTRIBUTING.md	Contribution guide and code standards	Contributors
LAUNCHER_GUIDE.md	Performance launcher documentation	Power users

⬆ Back to top

🛠 Troubleshooting

Common Issues

"Package has no installation candidate" — Run sudo apt-get update. On ZorinOS/derivatives, the script (v3.3.0+) automatically skips unavailable packages.

System upgrade hangs — Fixed in v3.2.0 with dpkg --force-confold. update to v3.5.0 or re-run with --skip-update.

NVIDIA driver not loading — Disable Secure Boot in BIOS. Run sudo apt purge nvidia-* && sudo python3 debian_gaming_setup.py --nvidia.

Steam won't launch — Run steam from terminal to see errors. Try rm -rf ~/.steam/steam/appcache/.

MangoHud not showing — Use MANGOHUD=1 %command% in Steam Launch Options. Config: ~/.config/MangoHud/MangoHud.conf.

Check logs — cat ~/gaming_setup_logs/gaming_setup_*.log | tail -100

Full troubleshooting guide | FAQ

⬆ Back to top

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/Sandler73/Debian-Gaming-Setup-Project.git
cd Debian-Gaming-Setup-Project
make install-dev   # Install pytest, pre-commit
make check         # Run all quality gates (lint + test + security)

⬆ Back to top

📊 Project Stats

Metric	Value
Script version	v3.5.0
Lines of code	5,796
Python version	3.12+ (StrEnum, slots, walrus, PEP 585/604)
CLI arguments	43 across 9 groups
GamingSetup methods	92+
Automated tests	136 (42 unit, 24 integration, 46 extended integration, 24 security/host safety)
CI/CD pipeline	4 jobs (lint, test matrix, security scan, release)
Gaming platforms	8
Performance tools	5
Supported distributions	10+ (tested)
Wiki pages	13
Configuration presets	4 (minimal, standard, complete, streaming)
Rollback action types	7
External dependencies	0 — Python standard library only
Security audit	STRIDE + CWE/SANS Top 25 mapped

⬆ Back to top

📜 License

MIT License — Free to use, modify, and distribute. See LICENSE for liability limitation and warranty disclaimer.

⚠️ Disclaimer

This script makes system-level changes. Always backup important data, test with --dry-run first, review logs for errors, and understand what's being installed. Use at your own risk. No warranty provided.

⬆ Back to top

💬 Support

Resource	Link
📖 Wiki & Guides	github.com/Sandler73/Debian-Gaming-Setup-Project/wiki
❓ FAQ	50+ Questions Answered
🐛 Report a Bug	Open Bug Report
✨ Request Feature	Open Feature Request
🔒 Security Issue	Private Security Advisory
💬 Discussions	GitHub Discussions
💝 Sponsor	GitHub Sponsors
📧 Contact	Open an Issue

Getting Help

Check the FAQ — 50+ questions across 12 categories
Read the Troubleshooting Guide — Common issues and solutions
Search existing issues — Your question may already be answered
Open a new issue — Use the structured issue templates for fastest response
Include your logs — cat ~/gaming_setup_logs/gaming_setup_*.log | tail -50

Supporting the Project

If this script helped you, consider:

⭐ Starring the repository
🐛 Reporting bugs you encounter
📝 Contributing code, docs, or translations
💝 Sponsoring via GitHub Sponsors
📢 Sharing with fellow Linux gamers

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
FAQ.md		FAQ.md
LAUNCHER_GUIDE.md		LAUNCHER_GUIDE.md
LICENSE		LICENSE
Makefile		Makefile
QUICK_START.md		QUICK_START.md
README.md		README.md
SECURITY.md		SECURITY.md
USAGE_GUIDE.md		USAGE_GUIDE.md
debian_gaming_setup.py		debian_gaming_setup.py

Latest commit

History

Folders and files

Repository files navigation

Debian-Based Gaming Setup Script

Transform your Debian-based Linux system into a complete gaming powerhouse

📋 Table of Contents

🖥️ Supported Operating Systems

🌟 What's New

v3.4.4 — CI/CD Overhaul & Node 24 Migration

v3.4.3 — Wiki Expansion & Version Automation

v3.4.1–v3.4.2 — Audit Remediation & Bug Fixes

v3.4.0 — Project Infrastructure

🚀 Quick Start

One-Command Installation

Presets

Verify Before Installing

⭐ Key Features

📦 Installed Components

Gaming Platforms & Launchers

Compatibility Layers

Performance & Monitoring

Communication & Utilities

🔩 Hardware Support

🎯 Usage Examples

Complete Setups

Maintenance Operations

🎛️ Command-Line Options

Quick Reference

🔄 Rollback System

🗑️ Full Uninstall

🎮 Post-Installation

📁 File Locations

📖 Documentation

🛠 Troubleshooting

Common Issues

🤝 Contributing

📊 Project Stats

📜 License

⚠️ Disclaimer

💬 Support

Getting Help

Supporting the Project

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages