reims-vgpu
reims-vgpu is an experimental virtual GPU for macOS guests
What is it?
What it is
reims-vgpu is an experimental virtual GPU for macOS guests that lets the guest use accelerated graphics without modifying its operating system. It provides a QEMU device that the macOS paravirtual GPU driver attaches to, decodes the guest’s GPU command stream on the host, and executes it through Metal or Vulkan (via metal2vulkan).
Why it exists
The project exists to enable macOS running inside a VM to use high‑performance graphics while keeping the guest unchanged. It serves as a research platform for experimenting with host‑guest GPU pathways, correctness, and performance on both x86 and arm64 hosts.
Who should use it
Virtualization researchersmacOS virtualization enthusiastsSystems engineers working on GPU virtualizationDevelopers interested in Metal/Vulkan translation
Who should avoid it
Users seeking a stable, production-ready macOS virtualization solutionUsers requiring high-performance gaming without experimental overheadUsers who cannot manage complex VM provisioning and snapshot workflows
How it works
A quick walkthrough in plain English
How reims-vgpu works
Step 1 of 3
You interact with it
Open reims-vgpu, send a request, or connect it to your stack.
Features
Advantages
- Enables accelerated graphics for macOS VMs without modifying the guest OS
- High flexibility with multiple host/guest/backend pathways
- Research-quality implementation for experimentation and bring-up
- Automated VM provisioning and lifecycle scripts
Disadvantages
- Alpha stage software with no stable compatibility guarantee
- No guarantee of correctness; prone to visual glitches and synchronization bugs
- Requires complex manual setup for guest disk and firmware provisioning
- High complexity in host/guest/backend combinations
Installation
native
x86_64 Linux (KVM): 1. Ensure KVM is available and configured (e.g., `options kvm ignore_msrs=1`). 2. Build in-tree QEMU: `scripts/qemu-build/qemu-build.sh --target x86_64 --backend vulkan`. 3. Generate guest artifacts (OpenCore, OVMF, disk) using OSX-KVM. 4. Place artifacts in `vm/disks/` and `vm/ovmf/`. 5. Boot using `vm/boot-x86.sh`. arm64 Apple Silicon (HVF): 1. Install `macosvm` via Homebrew. 2. Build vendored QEMU: `scripts/qemu-build/qemu-build.sh --target aarch64 --backend metal`. 3. Provision guest from UniversalMac IPSW using `scripts/vmapple-provision/`. 4. Configure guest and capture snapshot using `scripts/vmapple-snapshot/` or `vm/boot-arm64.sh --snapshot`. 5. Boot using `vm/boot-arm64.sh`.
FAQ
Does reims-vgpu require a custom macOS driver installation?
No. reims-vgpu provides the QEMU device that the existing macOS paravirtual GPU driver (AppleParavirtGPU.kext) attaches to, meaning no custom guest driver installation is required.
What are the supported host/guest/backend combinations?
The project supports three pathways: x86_64 macOS guests on Linux hosts using Vulkan; arm64 macOS guests on Apple Silicon hosts using Metal; and arm64 macOS guests on Apple Silicon hosts using Vulkan via MoltenVK.
How should I handle guest disk images and firmware?
The repository does not ship ready-made macOS disk images. You must provision your own guest (e.g., using OSX-KVM for x86_64 or UniversalMac IPSW for arm64) and place the resulting artifacts in the expected locations under the `vm/` directory.
What is the recommended workflow for testing and development?
It is recommended to capture a 'golden' snapshot of a clean guest state. For day-to-day work, use the `--testing` flag to ensure the VM reverts to the snapshot on exit, preventing accidental corruption of your primary guest image.
Is this project suitable for production use?
No. The project is currently in Alpha and is considered research-quality. The QEMU device ABI, boot scripts, and backend behaviors are subject to change without stability guarantees.
Featured in Videos
YouTube tutorials and walkthroughs for reims-vgpu
Alternatives
Similar projects ranked by category, topics, and text overlap.
