Helping you build the ultimate macOS virtual machine, powered by KVM.
What's new? | Switch to dev branch... ⎋
Tired of all the restraints and poor performance of macOS VMs in hypervisors like VirtualBox or VMware? Well, the story changes when you run your virtual machines in kernel space. Welcome to the world of Kernel Virtual Machines.
You might be new to QEMU/KVM, or a long-time veteran - either way, this project aims to help you build a macOS virtual machine that can take full advantage of the power of KVM - but in a user-friendly and approachable way.
Scripts? Configs? QEMU arguments? A "qcow" file? Moo? If you need a little help wrapping your head around this stuff, feel free to check out the FAQs for some quick knowledge on the basics.
SussyMac v2.0 - Full virtual Hackintosh setup powered by ULTMOS.
- AutoPilot ⎋ Automatically generates a valid, customised, and ready-to-use QEMU config script in seconds.
- VFIO-PCI Passthrough Assistant ⎋ Advanced passthrough tinkering made easy with auto-detection and configuration walkthroughs.
- USB Passthrough Assistant Allows you to select any of your host's attached USB devices for use with the macOS guest, and automatically configures them.
- OpenCore Configuration Assistant Automatically mount and edit your OpenCore image from your host, using Network Block Devices.
- Boot Argument Assistant + AutoPatch Easily edit the macOS boot arguments of your OpenCore image, and even automatically apply relevant patches for your setup (e.g. AMD RX 5000 series black screen patch).
- Automatic System Checks Several check scripts can be used to make sure your system is correctly prepared for both passthrough and non-passthrough KVM.
- GPU Compatibility Checker Detects GPUs in your host system and checks them against a list of known compatible and incompatible macOS GPUs, providing a summary including any extra card-specific quirks.
- VFIO-IDs and IOMMU Helpers Auto-detects and lists IOMMU groups, VFIO-IDs, and checks if devices are stubbed to kernel driver correctly.
- Convert to XML for virt-manager ⎋ Easily convert any AutoPilot-generated QEMU scripts into an importable XML file for virt-manager (GUI). VFIO-PCI passthrough and USB configurations are also converted.
Tip
Click the ⎋ icon next to a feature to read more about it in greater detail.
As with all other virtual machines / hypervisors, you don't need an uber-powerful PC, but you should expect guest performance to be relative to your host's. Performance can change dramatically based on guest properties, such as virtual cores, allocated memory, and virtual CPU threads - but it really does boil down to how beefy your host's hardware is.
Here's a table with my best judgment on minimum, recommended, and best system requirements:
| Minimum | Recommended | Optimal | My Setup | |
|---|---|---|---|---|
| OS | linux-5.x | Linux Mint | Arch Linux | Arch Linux |
| Motherboard | Virtualisation UEFI |
Virtualisation UEFI IOMMU Intel VT-d / AMD-V |
Virtualisation UEFI IOMMU Intel VT-d / AMD-V Isolated PCI Lanes |
ROG STRIX Z490-E GAMING UEFI IOMMU Intel VT-d Isolated PCI lanes |
| CPU | ~2014 Intel / AMD Virtualisation 2 cores |
Intel i5 / Ryzen 5 Virtualisation 4-8 cores Hyperthreaded |
Intel i9 / Ryzen 9 Virtualisation 8-16 cores Hyperthreaded |
Intel Core i9-10900K 10 cores Hyperthreaded |
| Memory | 4 GB | 16 GB | 32 GB+ | 64 GB |
| Disk Type | SATA HDD | SATA SSD | NVMe SSD | NVMe SSD |
| Disk Space | 40 GB | 120 GB | 500 GB+ | 500 GB |
| Resolution | 1280x720 | 2560x1440 | 3840x2160 | 2560x1440 |
| GPU (VFIO) | - | AMD RX 580 | AMD RX 6600 XT | AMD RX 5700 XT |
Note
The recommended and optimal specifications are for reference only.
The project requires several other packages to function properly, while others can be optionally installed to enhance your experience.
All of the dependencies, both required and optional, are listed below.
Required
- Git 》
git - Wget 》
wget - QEMU 》
qemu-base/qemu-full - Libvirt 》
libvirt - DNSmasq 》
dnsmasq - Python 》
python
- Virtual Machine Manager (GUI) 》
virt-manager - Virsh 》
virsh - Discord Rich Presence (pypresence) 》
python-pypresenceor, using pip, installpypresence - Network Block Device (NBD) 》
nbdrequired for mounting the OpenCore image for editing on host system
Warning
You must have all of the required dependencies installed before using this project.
Tip
Optional dependencies can enhance your experience, such as using your VM in a GUI, or showing what macOS version you're currently running on your Discord profile.
Your experience is automatically adapted based on the dependencies you have installed. For example, if you have pypresence installed, Discord rich presence will be enabled automatically on AutoPilot scripts.
Shocker; KVM is a module built into the Linux kernel, not Windows Subsystem for Linux or some UNIX-like terminal. You need a full install of at least base Linux on your host. Don't try any of that VM inception shenanigans.
The easiest way to do this is by grabbing some mainstream Linux distro, like Ubuntu, Linux Mint, Manjaro, endeavourOS - among many, many others. You can pick any one you like. If it's Linux - you can use this project. I use Arch BTW.
It's easy to get up and running. Simply clone the repo using git.
Make sure you have all dependencies installed before getting started.
$ git clone https://github.com/Coopydood/ultimate-macOS-KVMTip
Alternatively, you can download the latest release here.
Okay, so you've cloned my repo, and cd'd into the directory. Great!
Now, before running the script - and to avoid the subsequent and inevitable gotcha - you should enable the libvirtd daemon first if it hasn't been already. Here's an example for Arch-based systems:
$ sudo systemctl enable libvirtdWarning
This command requires superuser privileges.
and/or check the status of the daemon with
$ systemctl status libvirtdOkay, now you're ready to use ultimate-macOS-KVM. Use the main.py file.
This is your main menu / central hub for the project and everything can be accessed from here.
$ ./main.pyCaution
Most sub-scripts included in the project should not be run on their own. Always use main.py unless the script was user-generated or stated otherwise.
...and you've come to the right place. ultimate-macOS-KVM includes several handy built-in tools to make VFIO-PCI passthrough (including GPUs) as pain-free as possible. Please see the documentation on how to get started with these tools.
Oh, and speaking of...
More detailed write-ups on the project and the scripts included, as well as some tutorials can be found on this repo's wiki.
This is continually updated and made better as the project develops. Feel free to help out and write your own!
Changelogs can be found on the releases page.
Tip
All documentation and changelogs are included in the docs folder for offline reading.
Alongside the tutorial and explanation documents, this project includes troubleshooting guides for a wide variety of issues - ranging from project issues such as those in AutoPilot, or other issues such as GPU passthrough.
You can search for your problem and find solutions in the Issues and Troubleshooting section of the project wiki.
Note
If an unexpected problem with the ULTMOS project itself arises, it may be a bug, and can be reported here.
This project has been designed to be updated and made better over time.
As you use it to generate your personal files, having to re-clone the entire repo yourself while preserving your files would be a right pain in the backside. Therefore, there's an automated updater script built right in that you can use to safely update in-place to newer versions of this project, without affecting any of your personal config files, virtual hard drives, or anything else not part of the project files. And, if an update dramatically changes directory structures from your current version, the updater automatically disables its in-place update mechanism to prevent data loss.
Of course, if you're just testing the project, then a "clean install" is probably still preferable.
Here's a few screenshots showing ultimate-macOS-KVM in action!
Tip
More screenshots of ULTMOS in action can be found included in the docs folder!
This is my way of giving back to the QEMU, KVM, and VFIO community. Please don't expect much as this is a passion project and not a priority in my life.
- I'm not responsible for any time you waste using this project.
- I'm not responsible if you make an oopsie whoopsie.
- Expect headaches. Some severe.
- You need a LOT of patience. I mean it. Despite me trying to alleviate some of the hassles, you WILL run into stupid gotchas that require trial and error out of my control.
- I'm by no means an expert on this stuff nor would I claim to be.
- I've simply made what I had to go through easier for you. Hopefully.
- Yes, my Python is pretty bad. But if it works, it works.
Caution
Do NOT run anything as sudo unless absolutely necessary. If you have an urge to then you need to break that habit asap.
Most of my scripts do not require superuser privileges, however, the ones that do are clearly marked with a yellow
Warning
This project contains a string of text known as an OS Key (OSK).
Apple uses this key to make it more difficult for non-Macintosh computers to run macOS, by requiring the key to be provided by the SMBIOS.
This OS key is widely available on the Internet and is no longer considered a "secret", and was even included in a public court document.
Apple has attempted to classify the OSK as a trade secret but has ultimately failed in doing so. As a result, it is freely included within this project, as with OSX-KVM.
These awesome people were generous enough to donate financially to help fuel the 3AM misadventures this project is made from. Thank you so much!
If you find this project helpful, and want to support development, you can sponsor it! Any and all donations are incredibly appreciated and never expected or required!
While I am the creator of these automation/ease-of-use scripts, this project is not possible without both the prior and current works of some very talented people. The people who have tested the project are also included.
- Dortania 》 Extensive documentation and Hackintosh development.
- Kholia 》 Development of scripts and documentation. ultimate-macOS-KVM is intended as an extension to OSX-KVM.
- thenickdude 》 Personal support throughout my KVM misadventures and countless community contribs. Cheers.
- vit9696 》 Author of many macOS hacks including kexts, and other source material used in this project. Probably knows the macOS boot process better than Apple.
- vu1tur 》 Open source dmg to img conversion tool; used and bundled in this project.
- Eversiege 》 Support and testing, та мій улюблений українець. Also made the project's main website.
- CyberneticSquid 》 Testing for me at stupid-o'-clock because he's a cool Aussie.
- Cake 》 Another Aussie testing for me in the middle of my sleep-deprived nights, with a slight obsession over cake.
- Hyperchromiac 》 My personal constitution-munching American. Legend has it that I live in his attic, although even I'm not sure. Love this guy either way.
- Kaz 》 Other than his brilliant English accent's pronunciations (including "macOS Syria"), he's done extensive testing. Say hi to your nephew for me.
- GigantTech 》 Moderately annoying German guy that I convinced to install Linux subsequently letting him test my project. It's free real estate!
