Documentation

About Verjuice

Verjuice is a compatibility orchestrator: it runs Windows applications on Apple Silicon Macs without making you hand-configure Wine. Getting a Windows app running outside Windows normally means choosing a runtime, building a prefix, picking a DirectX translation layer and tuning it for your GPU. Verjuice makes those decisions for you: it looks at your hardware and at the app, picks a pipeline that already works for setups like yours, and launches the app.

Three things it is not:

• Not a virtual machine. No Windows is installed or emulated. Windows API calls are translated in real time — Wine and Whisky on macOS — so there is no Windows image, license or desktop involved.
• Not a DRM bypass. Verjuice launches apps through the store clients and runtimes you already have. Titles whose DRM or kernel anti-cheat blocks translation layers are marked Unsupported in the compatibility database, never patched or worked around.
• Not a bundle of proprietary code. Verjuice itself is open source (GPL-3.0-or-later), and so are the runtimes it installs and drives — Wine, DXVK, DXMT, MoltenVK and the community-maintained Whisky fork — used under their own licenses. Apple's D3DMetal is the one exception: proprietary, so Verjuice only uses it where it's already on your Mac (see below). The third-party notices page lists every component and its license.

Capabilities

What the shipped engine does today. The CLI and the GUI are the same engine, so this list applies to both.

• Hardware detection. Every launch starts by detecting your CPU, GPU, driver and installed runtimes, so recommendations are based on the machine you actually have.
• Compatibility database. Per-title ratings for that executable on your kind of host, backed by cited reports — who tested it, on what hardware, with which versions.
• Automatic routing. Wine or Whisky, with the right translation layer: DXVK and MoltenVK, plus DXMT and D3DMetal — the latter only when it's already on your Mac. If there's no working path on your Mac, it says so and explains why instead of trying anyway.
• Isolated prefixes. One per app under ~/.local/share/verjuice/prefixes/, never shared, so a broken app can't take others down with it.
• Installer support. verjuice install-file runs .exe, .msi, .zip, .pkg and .dmg installers, optionally launching and registering the app afterwards.
• Standalone executables. Register an .exe that has no installer and launch it by name — custom apps get a machine-local custom: id.
• Crash diagnosis. --heal watches the startup window and, if the app crashes, diagnoses the log against recorded fixes and tries again.
• Offline launches. Launching never needs the network. Registration still works offline and syncs when you're back.

Install

Download the macOS build from the download section or from GitHub Releases.

macOS (Apple Silicon)

Unzip the download and drag Verjuice into Applications. DirectX 12 titles on macOS need Apple Silicon: they run through Apple's D3DMetal, which Verjuice uses only if it's already on your Mac — see D3DMetal and DirectX 12 on macOS below for what that means and where Apple distributes it.

About the warning: the first time you open Verjuice, macOS says it “can't verify the app is free of malware.” That is not a malware finding — no scan ran. It's macOS noting that we haven't paid for Apple's notarization review, which every independently distributed Mac app without a paid developer certificate gets. If you'd rather not take our word for it, compare your download's SHA-256 digest against the one published on the release page (see verify the download) — if they match, the file is byte-for-byte what we published.

To open it anyway: double-click once, then open System Settings → Privacy & Security, scroll to the message saying Verjuice was blocked, and click Open Anyway. Authenticate and it opens — you only do this once.

Prefer a terminal install? This command downloads the ZIP, extracts it, and puts Verjuice in your personal Applications folder. Files fetched with curl also skip the browser quarantine flag:

After it finishes, open ~/Applications/Verjuice.app. If macOS still blocks it, use the System Settings → Privacy & Security → Open Anyway step above.

Prefer the terminal? The CLI lives inside the bundle: Verjuice.app/Contents/MacOS/verjuice — the same engine the window uses. It is not on your PATH.

Verify the download

Every release lists a SHA-256 digest for each file. Compare it with the one you compute locally before running anything:

No account, no key

Verjuice has no account, no key and no sign-in. Everything the paid tiers once unlocked is free, and nothing is uploaded: your tracked apps and settings live on your own machine.

If you used an older build that asked for a key, it still works — the old key check now answers “free, unlimited” for everyone. Update to the latest release and the prompt is gone.

Run your first app

In the commands below, verjuice means Verjuice.app/Contents/MacOS/verjuice — or just open the app; it's the same engine, and the GUI walks you through the same steps.

First, the one-time component setup. Nothing downloads until you confirm:

then approve what it found:

Starting from an installer file (.exe/.msi/.zip/.pkg/.dmg):

Starting from a standalone .exe, register it first — custom apps get a machine-local custom: id:

For a title already in the compatibility database:

Every launch works through four steps and prints each one: detect your CPU, GPU, driver and installed runtimes; query the compatibility ratings for that executable on your kind of Mac; route it to Wine or Whisky with the right translation layer; and launch it in an isolated prefix. If there's no working path on your Mac, it says so and explains why instead of trying anyway. Adding --heal watches the startup window and, if the app crashes, diagnoses the log against recorded fixes and tries again.

Where Verjuice keeps things

• Prefixes: ~/.local/share/verjuice/prefixes/, one per app, never shared.
• Logs: ~/.local/share/verjuice/logs/, with the exact configuration each launch used. Attach the log when you report a problem.
• Registrations and settings: ~/.local/state/verjuice/ — machine-local by design.

Tracked apps

Registering an app tracks it in your local profile. There is no limit and nothing to upgrade: register as many as you like, and remove one any time to stop tracking it.

D3DMetal and DirectX 12 on macOS

DirectX 12 titles on macOS run through Apple's D3DMetal, which translates DirectX 12 to Metal. D3DMetal is proprietary Apple software, distributed only under Apple's own license terms. That is why Verjuice never downloads it, bundles it, or installs it: the component is Apple's, the license is Apple's, and whether to accept those terms is entirely your decision. Verjuice doesn't require it — the component is used only where it is already present on your Mac.

The facts

• D3DMetal ships inside Apple's Game Porting Toolkit disk image. Apple describes the toolkit on its Game Porting Toolkit page and distributes downloads through its developer downloads site.
• Obtaining it involves signing in with an Apple ID and accepting Apple's license agreement. That agreement is between you and Apple; Verjuice is not a party to it and takes no position on it.
• Apple distributes it for Apple Silicon Macs on current versions of macOS, and the macOS requirement moves with each toolkit release. Intel Macs have no DirectX 12 path.
• The disk image includes a Read Me with Apple's own instructions for installing the D3DMetal runtime; Apple's documentation is the authoritative source for the exact steps and paths.

If it is present

Verjuice detects installed runtimes on every launch. Where D3DMetal is present, DirectX 12 titles are routed through it; where it isn't, Verjuice says so instead of pretending otherwise. The launch log in ~/.local/share/verjuice/logs/ records exactly what each launch detected and used.

Only DirectX 12 needs it. If you'd rather not accept Apple's terms, nothing else is affected: DirectX 9–11 titles still work through DXVK and MoltenVK.

Common fixes

• macOS warns the first time you open Verjuice: expected for any independently distributed Mac app without notarization — it's not a malware finding. Install explains what it means and how to get past it.
• macOS says the app is “damaged”: a stricter version of the same first-open check, not actual corruption. In Terminal: xattr -dr com.apple.quarantine /Applications/Verjuice.app removes the download flag, then open normally.
• A DirectX 12 title says D3DMetal is missing: D3DMetal is Apple's proprietary DirectX 12 translator, and Verjuice can't install it for you — D3DMetal and DirectX 12 on macOS explains what it is and where Apple distributes it.
• An app won't start: check its log in ~/.local/share/verjuice/logs/, then open an issue with the log attached.
• It works on your machine and isn't rated yet: submit a compatibility report.
• Titles with DRM or kernel anti-cheat that block translation layers are marked Unsupported. Verjuice never works around them.
• Anything else: support@verjuice.app.