1 09 macOS Host Support

Martin Wimpress edited this page 2026-01-24 13:57:47 +00:00

Table of Contents

• macOS QEMU 3D Acceleration
• Current State
• How 3D Acceleration Works on macOS
• GL Mode Comparison
• How to Get GL-Enabled QEMU
• Option A: Homebrew Tap (Recommended)
• Option B: Build from Source
• Option C: UTM
• Building a Nix Package with VirGL Support
• Quickemu Support
• Version Requirements
• Troubleshooting
• "OpenGL support was not enabled in this build of QEMU"
• Verifying GL is working
• Guest shows software rendering despite GL-enabled QEMU
• Performance is poor with GL enabled
• References

macOS QEMU 3D Acceleration

This guide covers 3D graphics acceleration for VMs running on macOS hosts. Stock QEMU packages lack OpenGL support on macOS, but acceleration is possible with patched builds.

Current State

Stock Homebrew and Nixpkgs QEMU on macOS lack OpenGL support. This is by design - the OpenGL dependencies (libepoxy, virglrenderer) target Linux in these packages.

The result: software rendering only, which is slower but stable.

How 3D Acceleration Works on macOS

macOS deprecated OpenGL in favour of Metal. To enable GPU acceleration in QEMU:

1. ANGLE translates OpenGL ES calls to Metal
2. virglrenderer provides VirGL 3D support to guests
3. gl=es display option enables this pathway (not gl=on or gl=core)

This requires patched QEMU and virglrenderer builds with ANGLE integration.

GL Mode Comparison

Mode	Backend	Stability	Performance	Notes
gl=off	Software	Stable	Slow	Default for stock QEMU
gl=core	Native OpenGL.framework	Unstable	Variable	macOS OpenGL is deprecated
gl=es	ANGLE/Metal	Stable	Fast	Recommended when available

How to Get GL-Enabled QEMU

Option A: Homebrew Tap (Recommended)

The simplest method using Konstantin Nazarov's maintained tap:

brew install knazarov/qemu-virgl/qemu-virgl

Repository: https://github.com/knazarov/homebrew-qemu-virgl

Option B: Build from Source

Building requires Akihiko Odaki's patched forks.

Dependencies:

brew install glib meson pipenv pixman pkg-config spice-protocol

Required repositories:

• QEMU: https://github.com/akihikodaki/qemu
• virglrenderer: https://github.com/akihikodaki/virglrenderer
• libepoxy (with macOS support)
• ANGLE libraries

Configure flags:

./configure \
  --enable-cocoa \
  --enable-opengl \
  --enable-virglrenderer \
  --enable-hvf \
  --target-list=aarch64-softmmu,x86_64-softmmu

For detailed build instructions, see Odaki's guide: https://gist.github.com/akihikodaki/87df4149e7ca87f18dc56807ec5a1bc5

Option C: UTM

UTM bundles all patches and ANGLE libraries in a GUI application:

https://github.com/utmapp/UTM

Pre-packaged with everything needed for GL acceleration, but provides a GUI rather than CLI.

Building a Nix Package with VirGL Support

Creating a custom Nix overlay for GL-enabled QEMU on macOS requires:

1. Override openGLSupport = true in the QEMU derivation
2. Add macOS-compatible dependencies:
   • libepoxy (with macOS/ANGLE support)
   • virglrenderer (from Odaki's fork or with his patches)
   • ANGLE libraries (libEGL.dylib, libGLESv2.dylib)
3. Apply patches from Odaki's QEMU fork

Note: Upstream QEMU and Nixpkgs do not fully support this configuration. You will need to:

• Patch virglrenderer for OpenGL ES compatibility
• Ensure ANGLE libraries are available at runtime via DYLD_LIBRARY_PATH or installed in the package prefix

Reference the build scripts in Odaki's repository for patch requirements.

Quickemu Support

PR #1812 adds automatic GL detection and enablement for macOS hosts.

How it works:

1. check_cocoa_gl_es_support() tests whether QEMU accepts gl=es:

   qemu-system-* -display cocoa,gl=es -M none
   

2. Also checks for ANGLE libraries (libEGL.dylib) in:
   • QEMU's prefix (<qemu-dir>/lib/)
   • Homebrew locations (/opt/homebrew/lib/, /usr/local/lib/)
   • DYLD_LIBRARY_PATH entries
3. Automatically uses gl=es when available
4. Falls back to gl=off for stock QEMU builds

Display devices used:

Guest Architecture	GL Device
x86_64	virtio-vga-gl
aarch64	virtio-gpu-gl-pci

Diagnostic output:

When GL is enabled, quickemu displays:

 - Display:  COCOA, virtio-vga-gl, GL (es), VirGL (on) @ (1280 x 800)

When falling back to software rendering:

 - Display:  COCOA, virtio-vga, GL (off), VirGL (off) @ (1280 x 800)

Version Requirements

Component	Minimum	Recommended
QEMU	6.0+	8.0+ with Odaki patches
macOS	11.0 (Big Sur)	13.0+ (Ventura)
virglrenderer	0.9.0+	Latest from Odaki fork

Troubleshooting

"OpenGL support was not enabled in this build of QEMU"

You are using stock QEMU without GL support. Install a GL-enabled build (see options above).

Verifying GL is working

From quickemu output:

Look for GL (es) and VirGL (on) in the display status line.

Inside the guest:

glxinfo | grep "OpenGL renderer"

Should show something like:

OpenGL renderer string: virgl (ANGLE (Apple, Apple M2, OpenGL 4.1 Metal - 89.4))

Guest shows software rendering despite GL-enabled QEMU

1. Verify ANGLE libraries are accessible:

   ls -la /opt/homebrew/lib/libEGL.dylib  # Homebrew location
   

2. Check QEMU accepts gl=es:

   qemu-system-aarch64 -display cocoa,gl=es -M none
   

   No error output means GL is supported.

3. Ensure the guest has Mesa with virgl support installed.

Performance is poor with GL enabled

• Verify you are using gl=es, not gl=core
• Check Activity Monitor for GPU usage - Metal should show activity
• Some guests may need updated Mesa drivers for optimal virgl performance

References

• Akihiko Odaki's Guide: https://gist.github.com/akihikodaki/87df4149e7ca87f18dc56807ec5a1bc5
• Odaki's QEMU Fork: https://github.com/akihikodaki/qemu
• Odaki's virglrenderer Fork: https://github.com/akihikodaki/virglrenderer
• Homebrew Tap: https://github.com/knazarov/homebrew-qemu-virgl
• UTM Project: https://github.com/utmapp/UTM
• ANGLE Project: https://chromium.googlesource.com/angle/angle
• Quickemu PR #1812: https://github.com/quickemu-project/quickemu/pull/1812