How well it runs can still depend on your host and its GPU. Metal, macOS are trademarks of Apple Inc. Reims vGPU is an independent project and is not affiliated with, sponsored by, or endorsed by Apple Inc.
Troubleshooting
By symptom. Start with reims-ctl doctor, which checks the host and the install and says what to do about what it finds.
An x86-64 guest stays on its wallpaper, or comes up gray with no Dock
It needs Metal's error mode, set once. Without it, macOS's icon service crashes as soon as it starts. Set it from macOS Recovery, as the Linux guide shows, or, if you have a desktop, from its Terminal, then restart:
$ sudo defaults write /Library/Preferences/.GlobalPreferences METAL_ERROR_MODE -int 5A Dock icon stays blank
Clear the Dock's icon cache, in the guest's Terminal:
$ rm -rf "$(getconf DARWIN_USER_CACHE_DIR)com.apple.dock.iconcache"; killall DockShortcuts go to the host, or the pointer leaves the window
Input isn't captured: the window's title ends click to capture input. Click into the guest's picture; the title then says how to release it, ⌃⌥⌘ on a Mac and Ctrl+Alt+Super on Linux. Switching to another window releases it too. Fn/Globe never reaches the guest.
Installing from an IPSW fails, asking for the virtualization entitlement
Only a reims-ctl signed with com.apple.security.virtualization can install macOS, and a plain cargo install leaves the signature out. Run the installer again from your checkout; reims-ctl doctor confirms the entitlement.
$ scripts/install-ctl.shLinux: a warning about vm.max_map_count
The guest's memory needs more kernel mappings than the stock limit allows. Raise it, and keep it across reboots with a file in /etc/sysctl.d:
$ sudo sysctl -w vm.max_map_count=2097152
$ echo vm.max_map_count=2097152 | sudo tee /etc/sysctl.d/90-reims-vgpu.confLinux: a VM on an AMD GPU can't open /dev/udmabuf
On AMD GPUs, the guest's memory reaches the GPU through /dev/udmabuf. Join the group that owns it, kvm on Ubuntu, and log in again:
$ sudo usermod -aG kvm $USERLinux: doctor fails "desktop session" over SSH
A VM's windows need a Wayland or X11 session, which an SSH login doesn't have. Start the VM from the desktop, or use the terminal viewer to see its screen from the SSH session.
x86-64: a display wider than 2048 pixels fails, or Chrome isn't GPU-accelerated
The VM's OpenCore image predates ReimsVgpu.kext, which macOS 26 needs for both. Make it a new image that presents the same Mac (details):
$ reims-ctl update
$ reims-ctl update-opencore macx86-64: YouTube in Safari shows "An error occurred"
Safari's media players need an audio output device. Turn the VM's audio back on: reims-ctl set mac --audio.
x86-64: Finder shows icons instead of thumbnails
Known, for images and videos: macOS's thumbnail extensions end when they first look for Metal's devices, and no setting in the guest avoids it.
Is it the GPU or the guest?
On Linux, run the VM on QEMU's VMware SVGA for a start: one display, no acceleration, in QEMU's own window. If the problem stays, it isn't the GPU. Switch back after.
$ reims-ctl set mac --graphics vmware-svga
$ reims-ctl set mac --graphics reims-vgpureims-ctl update stops at git pull
The checkout has commits or changes of your own, so it can't fast-forward. Update the checkout yourself, then run scripts/install-ctl.sh.
Anything else
Turn the VM's logs on, reproduce the problem, and write a report: it zips the logs, settings, QEMU command and the host's details into your Downloads folder. Attach it to an issue, or bring it to the Discord.
$ reims-ctl set mac --logs
$ reims-ctl start mac
$ reims-ctl report mac