reims-vgpu: An Experimental Virtual GPU for macOS Guests on QEMU

The Design Insight: macOS Already Has the Driver

Every modern macOS release ships with a kernel extension named AppleParavirtGPU.kext. This kext is a paravirtual GPU driver that exists to communicate with a host-provided virtual GPU device. The problem is that no public QEMU device speaks the protocol that kext expects, so the driver sits unused in every macOS VM running under standard QEMU.

reims-vgpu fills that gap. It implements the QEMU device side of the protocol, attaches to AppleParavirtGPU.kext inside the guest, intercepts the GPU command stream that the guest's Metal workloads produce, and executes those commands on the host through either Metal or Vulkan. The guest operating system stays unchanged. There is no custom kext to sign, no kernel extension policy to disable, and no driver package to install inside the VM.

The Vulkan path on Linux and on macOS uses a dependency named metal2vulkan, a public Rust crate maintained by the same author, which translates Metal command semantics to Vulkan. On Apple Silicon hosts running the Vulkan backend, MoltenVK provides the Vulkan layer on top of the host's Metal API.

Three Host and Guest Combinations

The README defines three pathways, each describing a specific host operating system, guest operating system, device attach method, and host backend.

The x86 macOS on Linux Vulkan pathway runs a 64-bit macOS 13 Ventura guest on a Linux x86_64 host with KVM. The QEMU device attaches over PCI as reims-vgpu-pci. The host backend is Vulkan via metal2vulkan. Boot uses vm/boot-x86.sh.

The arm64 macOS on macOS Metal pathway runs an arm64 macOS guest on an Apple Silicon host with HVF (the macOS Hypervisor framework). The device attaches over sysbus MMIO as reims-vgpu-mmio using QEMU's vmapple machine type. The host backend is Metal directly. Boot uses vm/boot-arm64.sh.

The arm64 macOS on macOS Vulkan pathway uses the same host and guest as the Metal pathway but routes the backend through metal2vulkan and MoltenVK instead of calling Metal directly. This lets the Vulkan backend code path be exercised on Apple Silicon.

All three pathways share the same QEMU device shim in vendor/qemu and the same Rust product crate at crates/reims-vgpu, which handles decode, the device model, and the backend selection.

Getting Started with the x86 Linux Pathway

The README is explicit that reims-vgpu does not ship a macOS disk image. Before using the device, you need a working macOS 13 Ventura guest built with OSX-KVM or another tool, plus the usual OpenCore and OVMF pieces. The steps below follow the README for the x86 pathway.

First, build the in-tree QEMU with the Vulkan backend enabled:

scripts/qemu-build/qemu-build.sh --target x86_64 --backend vulkan

Once you have a working guest disk, OpenCore, and OVMF placed in the paths vm/boot-x86.sh expects, capture the first rail snapshot. The rail system keeps a golden image that reims-vgpu boots from a copy-on-write clone on every run, discarding the clone on exit:

mkdir -p vm/disks/rails/macos-15
vm/boot-x86.sh --rail macos-15 --capture --device vmware-svga

For day-to-day testing with the reims-vgpu device once the host Vulkan stack is confirmed working:

vm/boot-x86.sh --testing --device reims-vgpu-pci --rail macos-15

The README recommends using --device vmware-svga first to confirm the guest boots cleanly before switching to reims-vgpu-pci.

The arm64 Bring-up on Apple Silicon

The Apple Silicon pathway uses Virtualization.framework via a Homebrew tool named macosvm rather than OSX-KVM. There is no separate OpenCore step because vmapple boots the guest directly through the macOS hypervisor.

Start by building the vendored QEMU for arm64 with the Metal backend:

scripts/qemu-build/qemu-build.sh --target aarch64 --backend metal

The README then directs users to scripts/vmapple-provision/ to provision a guest from a UniversalMac IPSW file. The guest bundle lives under vm/guest/, holding the disk image, auxiliary data, and a vm.json or ECID file.

The arm64 bring-up is described as in-tree, meaning the tooling to provision and boot the guest is included in the repository. This contrasts with the x86 pathway, which delegates the initial guest installation to an external project. For the arm64 pathway, the README expects the developer to follow the scripts/vmapple-provision/ helper tooling directly.

Rust Crate Layout and the QEMU Shim

The Cargo workspace in the repository root defines ten crate members. The main product crate is crates/reims-vgpu, which contains the protocol decode logic, device model, and Metal and Vulkan backends. Supporting crates handle specific concerns: reims-vgpu-core for core abstractions, reims-vgpu-wire for serializer views and parsers used by the decode logic, reims-vgpu-vulkan for the Vulkan backend, reims-vgpu-memory and reims-vgpu-paging for memory management, reims-vgpu-observe for observability, reims-vgpu-config for configuration, reims-vgpu-protocol for the wire protocol definitions, and reims-vgpu-testkit for testing utilities.

The QEMU device shim in vendor/qemu is a thin C layer covering QOM, MMIO, IRQ, and console handling. It calls into the Rust staticlib produced by the workspace. The Cargo.toml release profile uses LTO fat, opt-level 3, and a single codegen unit, since the product hot path is in the Rust layer and that is where CPU time matters.

A separate crate, reims-vgpu-efi, lives in crates/ but is excluded from the workspace because it targets x86_64-unknown-uefi and would pull in a no_std PE graph incompatible with the rest of the build.

Alpha Status and the Constraints It Creates

The README labels reims-vgpu as Alpha and uses the phrase research-quality to describe its maturity. The QEMU device ABI, boot scripts, crate layout, and backend behavior may change without a stable compatibility guarantee. This is not a hedging disclaimer: it describes the actual state of a project where bring-up and correctness are the primary open problems.

The README lists the areas where contributions are most wanted: correctness, visual glitches, synchronization bugs, command-stream decoding, Metal/Vulkan translation, and making specific host/guest combinations more reliable. These are the categories of work that separate a bring-up prototype from a stable hypervisor device.

The last push was on 2026-09-03. The project has an active Discord server linked from the README, which the README targets as the collaboration channel for developers interested in working on the codebase. The LGPL-3.0 license permits use in proprietary software as long as changes to the library itself are shared, which matters for any organization building a commercial hypervisor product on top of reims-vgpu.

Comparison with UTM and Software Rendering

UTM is a widely used macOS application for running virtual machines that wraps QEMU with a graphical interface. It supports both x86 and arm64 guests. For most users who want to run a macOS or Linux VM on macOS, UTM works without build steps, kernel configuration, or disk image management scripts.

UTM does not provide GPU acceleration for macOS guests in the way reims-vgpu attempts. macOS VMs under UTM use software rendering, which limits graphical performance. Applications that depend on Metal for rendering or compute will either fail or run at unusably slow frame rates under software rendering.

reims-vgpu targets this specific gap: GPU-accelerated graphics inside a macOS guest. The trade-off is that it requires manual QEMU builds, a hand-provisioned guest image, and tolerance for an alpha-quality codebase. UTM is the appropriate choice for anyone who needs a working VM today without those constraints. reims-vgpu is the appropriate choice for developers willing to contribute to solving the GPU acceleration problem.

Editorial conclusion

reims-vgpu is research-quality software, as the README states. It is the right starting point for engineers willing to work on an early virtualization codebase and interested in macOS GPU passthrough on either Linux KVM or Apple Silicon HVF. Teams running macOS VMs in production and expecting a stable framebuffer with no setup friction should not adopt it in this state. The QEMU device ABI, boot scripts, and backend behavior may change without a compatibility guarantee. Before experimenting, verify you have a working macOS 13 Ventura guest, the correct Vulkan or Metal stack on the host, and patience for the bring-up steps documented in vm/boot-x86.sh or vm/boot-arm64.sh.

Frequently asked questions

Official sources

1. Issues
2. License: LGPL-3.0
3. Project website
4. README
5. steelbrain/reims-vgpu on GitHub