Run Windows programs
winbridge run starts a Windows program on Linux. This page covers running an app, the per-app environments WinBridge creates, faster Direct3D, extra runtimes, and adding an app to your desktop launcher.
Run a program
winbridge run path/to/app.exeArguments for the app itself go after --:
winbridge run path/to/app.exe -- --some --app-flagsEach run does four things:
- Checks the file. If it is not a Windows executable, WinBridge says so instead of handing it to Wine.
- Finds a Wine runtime. Wine is the compatibility layer that runs Windows programs on Linux. WinBridge uses, in order: the one named by
WINBRIDGE_WINE, its own managed runtime, then anywineon yourPATH. If none exists, it downloads its pinned Wine build (about 94 MB) into~/.cache/winbridge/runtimes/and verifies the checksum. - Selects the app's prefix, creating it on the first run.
- Runs the app from the app's own folder.
A console program prints to your terminal, and its exit code becomes the exit code of winbridge run, so it works in scripts and pipes:
winbridge run tool.exe -- --version | grep 1.2A program with a window opens on your desktop, and winbridge run waits until you close it. Wine's own diagnostic messages are hidden; add --verbose to see them, along with the runtime path, the prefix and the exact command.
Good to know
Whether a particular app works depends on Wine. WinBridge does not keep a compatibility database. The binaries WinBridge builds are 64-bit, and that is the tested path.
Prefixes: one Windows environment per app
A prefix is a private Windows environment: its own C: drive, registry and settings. WinBridge gives every app its own, named after the executable. game.exe gets the prefix game; Setup.exe gets Setup. An installer that breaks its own environment cannot affect any other app.
Prefixes live in ~/.local/share/winbridge/prefixes/.
| Task | Command |
|---|---|
| List prefixes, with DXVK state | winbridge prefix list |
| Use a named prefix | winbridge run app.exe --prefix shared |
| Delete a prefix | winbridge prefix delete game |
Two programs that must see each other, such as an installer and the app it installs, need the same --prefix name.
The first run in a new prefix takes longer, because Wine creates the C: drive and registry.
DANGER
winbridge prefix delete removes the prefix folder and everything in it at once, without asking: the installed app, its settings and any files it saved inside its Windows environment. Copy out anything you want to keep first.
Deleting a prefix is also how you reset an app that misbehaves. The next run builds a fresh one.
Faster Direct3D with DXVK
Wine translates Direct3D, the Windows 3D graphics interface, to OpenGL. DXVK translates it to Vulkan instead, which usually suits 3D applications and games better. WinBridge installs DXVK per prefix.
| Command | Effect |
|---|---|
winbridge run game.exe --dxvk | Installs DXVK into the app's prefix and uses it. |
winbridge run game.exe | Keeps using DXVK. The setting is remembered per prefix. |
winbridge run game.exe --no-dxvk | Goes back to Wine's own Direct3D. |
DXVK needs a working Vulkan setup. winbridge doctor reports whether a Vulkan loader is present, and --dxvk stops with an explanation when there is none. The check confirms the loader is installed, not that your graphics driver is configured.
--no-dxvk stops Wine from loading DXVK but leaves its files in the prefix. For a clean environment, delete the prefix.
The WinBridge project states that DXVK installation is tested but actual Direct3D rendering through it is not verified by its own test suite.
Install extra runtimes with winetricks
Some apps need components that Wine does not include: a Visual C++ redistributable, .NET, core fonts. winetricks is a tool that installs these into a prefix. WinBridge runs a pinned copy of it:
winbridge prefix tricks mygame corefonts vcrun2019The first word after tricks is the prefix name. The rest are winetricks verbs, the names of things to install.
| Command | Shows |
|---|---|
winbridge prefix tricks mygame list | Which verbs exist. |
winbridge prefix tricks mygame list-installed | What this prefix already has. |
Some verbs download a lot and take minutes. Output appears as it happens.
WARNING
WinBridge checks the checksum of winetricks itself. It cannot check what the verbs download: those files come from Microsoft and other third parties, and winetricks verifies them. Running winbridge prefix tricks means trusting winetricks and those servers, the same as running winetricks directly.
winetricks prints a warning that Wine's wow64 mode is experimental. WinBridge uses a wow64 build of Wine on purpose, so expect that message.
Recipes: saved setups for an installer
A recipe is a small JSON file that records what one specific installer needs: winetricks verbs, DLL overrides, and whether to turn DXVK on. A recipe is data only; WinBridge never executes anything from it.
| Command | What it does |
|---|---|
winbridge recipe list | Lists the recipes WinBridge can see and where each came from. |
winbridge recipe show Setup.exe | Fingerprints the file (SHA-256 and size) and shows the matching recipe and what it would do. Changes nothing. |
winbridge recipe apply Setup.exe | Applies the matching recipe to the app's prefix. Add --prefix to name the prefix. |
Put your own recipes in ~/.local/share/winbridge/recipes/. The release packages contain the winbridge program only, so recipe list shows what you add there. The format is described in the recipes README in the repository.
recipe apply stops at the first step that fails and does not undo the steps before it. Delete the prefix to start over.
Add an app to your desktop launcher
winbridge desktop add path/to/game.exe --name "My Game" --prefix gameThis writes a launcher entry, winbridge-<name>.desktop, in ~/.local/share/applications/. Selecting it runs winbridge run with that prefix. Both options are optional; without them the name and prefix come from the file name.
| Command | What it does |
|---|---|
winbridge desktop list | Lists the entries WinBridge created. |
winbridge desktop remove game | Removes one entry. WinBridge only removes entries it wrote. |
The entry calls winbridge by name, so winbridge must be on your PATH. That is true for the .deb and PPA installs. For the tarball install, make sure ~/.local/bin is on the PATH your desktop session uses.
Entries use a generic icon.
Use your own Wine
Set WINBRIDGE_WINE to the full path of a wine binary to use it instead of the managed one:
WINBRIDGE_WINE=/usr/bin/wine winbridge run app.exeWinBridge verifies only the runtime it downloads itself. A Wine you point it at runs on your say-so.