Installation

OpenBox runs on Linux (x86_64 and aarch64), Windows 10 and 11 (x86_64), and macOS 11 or newer (Apple Silicon and Intel). Pick the method for your system.

Choose a method

Method	Platform	Updates
Linux installer	Linux, x86_64 or aarch64	Built-in verified updater
AppImage by hand	Linux, x86_64 or aarch64	Built-in verified updater
Flatpak	Linux, x86_64	Your Flatpak update workflow
Source	Linux, Windows, macOS	git pull, then start again
Windows	Windows 10 and 11, x86_64	Built-in verified updater
macOS	macOS 11 or newer, Apple Silicon and Intel	Built-in verified updater

Linux installer

The installer selects the AppImage that matches your CPU. It then verifies the release key pin, the SHA-256 checksum, and the Ed25519 signature before it installs to ~/.local/bin. It needs curl, python3, openssl, and sha256sum.

VERSION=1.19.1
curl --proto '=https' --tlsv1.2 --fail --location \
  --output install.sh \
  "https://github.com/vindeckyy/OpenBoxGL/releases/download/v${VERSION}/install.sh"
less install.sh
OPENBOX_RELEASE_TAG="v${VERSION}" bash install.sh

Set VERSION to the release you want. The newest release is on the releases page. Add --run to the last command to start OpenBox when the install finishes. Set OPENBOX_INSTALL_DIR to install somewhere else.

AppImage by hand

Download the AppImage that matches your CPU from the latest release. Its file name ends in x86_64 or aarch64. Make the file executable, then run it:

chmod +x OpenBox-$(uname -m).AppImage
./OpenBox-$(uname -m).AppImage

Add --web to open the interface in a browser app window instead of the native window.

If the AppImage does not mount, install the FUSE 2 library. The package is libfuse2 on Debian and Ubuntu, libfuse2t64 on Ubuntu 24.04 and newer, fuse-libs on Fedora, and fuse2 on Arch. You can also run ./OpenBox-x86_64.AppImage --appimage-extract-and-run, which skips FUSE.

Flatpak

Download OpenBox-x86_64.flatpak from the latest release. Then install and run it:

flatpak install --bundle OpenBox-x86_64.flatpak
flatpak run io.openbox.GameLauncher

The Flatpak bundle is x86_64 only. The built-in updater does not update it, so use your Flatpak update workflow. The manifest grants access to your home folder, so keep game folders under home.

Source

Source installs need Python 3.10 or newer. OpenBox uses only the Python standard library.

git clone https://github.com/vindeckyy/OpenBoxGL.git
cd OpenBoxGL
python3 web_app.py

On Windows, run python web_app.py. The python3 command there is a Microsoft Store alias. On macOS, the Command Line Tools python3 can be older than 3.10, so install a current Python with Homebrew: brew install [email protected].

For the native window on Linux, install WebKitGTK 4.1, then run make native-host && ./openbox-native.sh.

Windows

Windows 10 and 11 on x86_64 install from the signed portable zip. You need Windows PowerShell 5.1 and Python 3.10 or newer on PATH. The installer checks the release key, the archive checksum, and the signature before it extracts anything.

$Version = '1.19.1'
Invoke-WebRequest -UseBasicParsing -OutFile OpenBox-x86_64-windows.zip `
  "https://github.com/vindeckyy/OpenBoxGL/releases/download/v$Version/OpenBox-x86_64-windows.zip"
Expand-Archive OpenBox-x86_64-windows.zip -DestinationPath .
Get-Content .\OpenBox\scripts\install.ps1   # read the script before you run it
powershell -ExecutionPolicy Bypass -File .\OpenBox\scripts\install.ps1 -Tag "v$Version"

The installer puts the app in %LOCALAPPDATA%\OpenBox\share\openbox. It adds a Start Menu shortcut, registers the openbox:// link handler, and adds the folder to your user PATH. The native window needs the WebView2 runtime, which ships with Windows 11 and most Windows 10 systems. Without it, OpenBox opens the interface in a browser app window.

macOS

macOS 11 or newer installs from the signed universal app bundle. The bundle includes its own Python. The installer needs python3 on your PATH to run the release verifier.

VERSION=1.19.1
curl --proto '=https' --tlsv1.2 --fail --location \
  --output install-macos.sh \
  "https://github.com/vindeckyy/OpenBoxGL/releases/download/v${VERSION}/install-macos.sh"
less install-macos.sh
OPENBOX_RELEASE_TAG="v${VERSION}" bash install-macos.sh

The installer places OpenBox.app in ~/Applications and links openbox into ~/.local/bin. Add --replace to update an existing install.

The bundle is ad-hoc signed and not notarized. On first launch, open System Settings > Privacy & Security and choose Open Anyway. Each new build asks again.

Platform support

Platform	CPU	What release CI covers
Linux (Ubuntu LTS release runners)	x86_64, aarch64	Release-gated build and test coverage. aarch64 has build and emulated smoke tests; physical hardware is unverified.
Windows 10 and 11	x86_64	Full test suite on windows-latest. No maintainer hardware pass.
macOS 11 or newer	arm64, x86_64	Full test suite on macos-15 and macos-15-intel. Hardware pass on Apple Silicon only.

Steam Deck has a gamescope test harness and controller-path coverage, but no physical maintainer pass. The full matrix is in SUPPORT.md.

Update

The AppImage, Windows, and macOS installs update through the built-in verified updater. On Windows and macOS, the updater keeps the previous copy beside the install. Flatpak installs follow your Flatpak workflow. A source checkout updates with git pull.

Uninstall

On Windows, run the uninstaller inside the install folder. Preview the changes first with -WhatIf:

powershell -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\OpenBox\share\openbox\scripts\uninstall.ps1" -WhatIf

The uninstaller removes the install, the PATH entry, the Start Menu shortcut, and the openbox:// registration. It keeps your library and settings.

On macOS, delete OpenBox.app from ~/Applications and remove the ~/.local/bin/openbox link. Your data stays in place.

For a system install from source, run sudo make uninstall.

Where your data lives

System	Library data folder
Linux	~/.local/share/openbox-game-launcher
Windows	%LOCALAPPDATA%\openbox-game-launcher
macOS	~/Library/Application Support/openbox-game-launcher

Set OPENBOX_DATA_DIR in the environment before launch to use another folder. OpenBox reads it at startup.

Verify the install

Open Settings, then About. The page shows the running version, the platform, the data folder, and whether OpenBox runs in a native window or a browser tab.

See also: Getting started and Troubleshooting. Full guides: Windows, macOS, and Updating.