v0.12.4

Helping you build the ultimate macOS virtual machine, powered by KVM.

What's new?   |   Switch to dev branch... ⎋

macOS Sequoia Support
_{Available Now}

macOS Sequoia has not yet been tested extensively, but it has been confirmed to install and boot with the current version of ULTMOS on the latest macOS version.

AutoPilot now has an additional option for macOS Sequoia!
Please feel free to try out the macOS Sequoia with ULTMOS and leave feedback on how it went!

👋》Introduction

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.

macOS Sequoia running on ULTMOS.

💎》Features

• Modern macOS Support ⎋
Experience the latest macOS has to offer with built-in support from macOS High Sierra to macOS Sonoma, and even try out the latest macOS Sequoia!
• 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.
• GenSMBIOS Integration
Auto-generate a new SMBIOS and serial number directly onto the virtual OpenCore image with full GenSMBIOS + ULTMOS integration.
• 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.

🎲》Requirements

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:

[!NOTE] The recommended and optimal specifications are for reference only.

macOS Guest Feature Support Matrix

| | | | | | | | | | |--------------------------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:---------:|:---------:| | **AutoPilot** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | **Auto
Download** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | **Online
Install** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | **Offline
Install** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | **QEMU
Script** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓¹ | ✓¹ | ✓¹ | | **Virt
Manager** | ✓ | ✓ | ✓ | ✓ | ✓ | ?² | ?² | ?² | | **GPU
Passthrough** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓¹ | ✓¹ | ✓¹ | | **VirtIO
Networking** | ✕ | ✕ | ?³ | ✓ | ✓ | ✓ | ✓ | ✓ | | **VirtIO
Storage** | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ¹ ^{If trying to boot macOS Ventura and later with GPU passthrough, you may need to do so using Virtual Machine Manager. The QEMU script may have issues with GPU passthrough. ² macOS Ventura and later have been known to have issues booting *without* GPU passthrough in Virtual Machine Manager. ³ I have no idea whether or not VirtIO networking works on macOS Catalina.
> [!NOTE] > This table is a very **loose** representation of the current state of macOS versions and their support with ULTMOS / QEMU / KVM. It's more for reference and shouldn't be taken seriously. > > If you find something is wrongly marked, please feel free to update it.}

📦》Dependencies

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.

[!IMPORTANT] The package names listed below are examples on an Arch-based system. Your distro may be different!

Required

• Sudo 》 sudo
• Git 》 git
• Wget 》 wget
• QEMU 》 qemu-full
• Libvirt 》 libvirt
• DNSmasq 》 dnsmasq
• Python 》 python

Optional

• Virtual Machine Manager (GUI) 》 virt-manager
• Virsh 》 virsh
• Discord Rich Presence (pypresence) 》 python-pypresence or, using pip, install pypresence
• Network Block Device (NBD) 》 nbd required for mounting the OpenCore image for editing on host system

[!WARNING] You must have all of the required dependencies installed before using this project.

[!NOTE] As of v0.12.0, some libraries, such as pypresence, are bundled with the project by default and require no further user action or installation.

[!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.

🐧》Oh, and you NEED Linux.

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 theoretically pick any one you like. I use Arch BTW.

[!NOTE] Testing of ULTMOS on different distrobutions is underway - but please note that is has been primarily developed and tested on Arch and Debian-based systems.

🛫》Getting Started

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-KVM

[!TIP] 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 libvirtd

[!WARNING] This command requires superuser privileges.

and/or check the status of the daemon with

$ systemctl status libvirtd

🧭》Usage

Okay, 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.py

[!CAUTION] 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.

🖥️》I'm here for GPU passthrough

...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.

[!TIP] If you're looking for single GPU passthrough, DarknessRafix has an excellent guide that walks you through the process of setting this up using ULTMOS. You can read it here.

Oh, and speaking of...

📖》Documentation

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.

🛟》Help and Troubleshooting

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.

⬇️》Updates

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.

🖼️》Gallery

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!

☢️》Disclaimer

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.
• I have no affiliation with OpenCore and have no developmental experience with it.
• 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 ⚠️ next to the operation requiring such permissions.

⚖️》Legal

[!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.

❤️》Sponsors

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!}

Powered by OpenCore
_{Version 0.9.7}

This project would not be possible without the incredible work of the OpenCore development team. Thank you to everyone involved! ❤️

🤝》Credits & Greetz

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.
• 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!
• Hummenix 》Testing of ULTMOS across different Linux distros.
• CorpNewt 》Creator of GenSMBIOS and many other Hackintosh essentials.
• Acidanthera 》The group behind OpenCore, Lilu, WhateverGreen, and MUCH more.
• [DarknessRafix]() 》Extensive testing of the project and the author of some excellent ULTMOS guides! Oh, and was the very first person to install macOS Sequoia on ULTMOS - even before me.